Skip to main content
@inferedge/moss / MossClient

MossClient

MossClient - Async-first semantic search client for vector similarity operations. All mutations (createIndex, addDocs, deleteDocs) are async operations that run server-side and poll until complete.

Example

import { MossClient } from '@inferedge/moss';

const client = new MossClient('your-project-id', 'your-project-key');

// Create an index with documents (polls until complete)
const result = await client.createIndex('docs', [
  { id: '1', text: 'Machine learning fundamentals' },
  { id: '2', text: 'Deep learning neural networks' }
]);

// Add docs (polls until complete)
await client.addDocs('docs', [
  { id: '3', text: 'Natural language processing' }
]);

// Query the index
await client.loadIndex('docs');
const results = await client.query('docs', 'AI and neural networks');

Constructors

Constructor

new MossClient(projectId, projectKey): MossClient
Creates a new MossClient instance.

Parameters

ParameterTypeDescription
projectIdstringYour project identifier.
projectKeystringYour project authentication key.

Returns

MossClient

Methods

createIndex()

createIndex(indexName, docs, options?): Promise<MutationResult>
Creates a new index with the provided documents via async upload. Handles the full flow: init → upload → build → poll until complete. Returns when the index is ready. When all documents have pre-computed embeddings, they are serialized as raw float32 in the binary upload. When no documents have embeddings, the server generates embeddings in batches (dimension=0 flow). Mixed documents (some with embeddings, some without) are rejected.

Parameters

ParameterTypeDescription
indexNamestringName of the index to create.
docsDocumentInfo[]Documents, optionally with pre-computed embeddings.
options?CreateIndexOptionsOptional model ID and progress callback.

Returns

Promise<MutationResult> Promise that resolves to MutationResult when the index is ready.

Throws

If the index already exists or creation fails.

Example

const result = await client.createIndex('knowledge-base', [
  { id: 'doc1', text: 'Introduction to AI' },
  { id: 'doc2', text: 'Machine learning basics' }
], {
  onProgress: (p) => console.log(`${p.status} ${p.progress}%`),
});

getIndex()

getIndex(indexName): Promise<IndexInfo>
Gets information about a specific index.

Parameters

ParameterTypeDescription
indexNamestringName of the index to retrieve.

Returns

Promise<IndexInfo> Promise that resolves to IndexInfo object.

Throws

If the index does not exist.

Example

const info = await client.getIndex('knowledge-base');
console.log(`Index has ${info.docCount} documents`);

listIndexes()

listIndexes(): Promise<IndexInfo[]>
Lists all available indexes.

Returns

Promise<IndexInfo[]> Promise that resolves to array of IndexInfo objects.

Example

const indexes = await client.listIndexes();
indexes.forEach(index => {
  console.log(`${index.name}: ${index.docCount} docs`);
});

deleteIndex()

deleteIndex(indexName): Promise<boolean>
Deletes an index and all its data.

Parameters

ParameterTypeDescription
indexNamestringName of the index to delete.

Returns

Promise<boolean> Promise that resolves to true if successful.

Throws

If the index does not exist.

Example

const deleted = await client.deleteIndex('old-index');

addDocs()

addDocs(indexName, docs, options?): Promise<MutationResult>
Adds or updates documents in an index asynchronously. The index rebuild happens server-side. This method polls until the rebuild is complete and then returns.

Parameters

ParameterTypeDescription
indexNamestringName of the target index.
docsDocumentInfo[]Documents to add or update.
options?MutationOptionsOptional configuration (upsert, onProgress callback).

Returns

Promise<MutationResult> Promise that resolves to MutationResult when the operation is complete.

Throws

If the index does not exist.

Example

const result = await client.addDocs('knowledge-base', [
  { id: 'new-doc', text: 'New content to index' }
], { upsert: true });
console.log(`Job ${result.jobId} completed`);

deleteDocs()

deleteDocs(indexName, docIds, options?): Promise<MutationResult>
Deletes documents from an index by their IDs asynchronously. The index rebuild happens server-side. This method polls until the rebuild is complete and then returns.

Parameters

ParameterTypeDescription
indexNamestringName of the target index.
docIdsstring[]Array of document IDs to delete.
options?MutationOptionsOptional configuration (onProgress callback).

Returns

Promise<MutationResult> Promise that resolves to MutationResult when the operation is complete.

Throws

If the index does not exist.

Example

const result = await client.deleteDocs('knowledge-base', ['doc1', 'doc2']);
console.log(`Job ${result.jobId} completed`);

getJobStatus()

getJobStatus(jobId): Promise<JobStatusResponse>
Gets the current status of an async job.

Parameters

ParameterTypeDescription
jobIdstringThe job ID returned by createIndex, addDocs, or deleteDocs.

Returns

Promise<JobStatusResponse> Promise that resolves to JobStatusResponse with progress details.

Example

const status = await client.getJobStatus(jobId);
console.log(`${status.status}${status.progress}%`);

getDocs()

getDocs(indexName, options?): Promise<DocumentInfo[]>
Retrieves documents from an index.

Parameters

ParameterTypeDescription
indexNamestringName of the target index.
options?GetDocumentsOptionsOptional configuration for retrieval.

Returns

Promise<DocumentInfo[]> Promise that resolves to array of documents.

Throws

If the index does not exist.

Example

// Get all documents
const allDocs = await client.getDocs('knowledge-base');

// Get specific documents
const specificDocs = await client.getDocs('knowledge-base', {
  docIds: ['doc1', 'doc2']
});

loadIndex()

loadIndex(indexName, options?): Promise<string>
Downloads an index from the cloud into memory for fast local querying. How it works:
  1. Fetches the index assets from the cloud
  2. Loads the embedding model for generating query embeddings
  3. Executes a local similarity match between the query embedding and the retrieved index.
Why use this?
  • Without loadIndex(): Every query() call goes to the cloud API (~100-500ms network latency)
  • With loadIndex(): Queries run entirely in-memory (~1-10ms)
Reload behavior: If the index is already loaded, calling loadIndex() again will:
  • Stop any existing auto-refresh polling
  • Download a fresh copy from the cloud
  • Replace the in-memory index
Auto-refresh (optional): Enable autoRefresh: true to periodically poll the cloud for updates. When a newer version is detected, the index is automatically hot-swapped without interrupting queries.

Parameters

ParameterTypeDescription
indexNamestringName of the index to load.
options?LoadIndexOptionsOptional configuration including auto-refresh settings.

Returns

Promise<string> Promise that resolves to the index name.

Throws

If the index does not exist in the cloud or loading fails.

Example

// Simple load - enables fast local queries
await client.loadIndex('my-index');

// Now queries run locally (fast, no network calls)
const results = await client.query('my-index', 'search text');

// Load with auto-refresh to keep index up-to-date
await client.loadIndex('my-index', {
  autoRefresh: true,
  pollingIntervalInSeconds: 300, // Check cloud every 5 minutes
});

// Stop auto-refresh by reloading without the option
await client.loadIndex('my-index');

query()

query(indexName, query, options?): Promise<SearchResult>
Performs a semantic similarity search against the specified index. If the index has been loaded via loadIndex(), runs entirely in-memory. Otherwise, falls back to the cloud /query endpoint.

Parameters

ParameterTypeDescription
indexNamestringName of the target index to search.
querystringThe search query text.
options?QueryOptionsOptional query configuration including topK (default: 5) and embedding overrides.

Returns

Promise<SearchResult> Promise that resolves to SearchResult with matching documents.

Throws

If the specified index does not exist.

Example

const results = await client.query('knowledge-base', 'machine learning');
results.docs.forEach(doc => {
  console.log(`${doc.id}: ${doc.text} (score: ${doc.score})`);
});