Asimov SDK

Official Node.js SDK for the Asimov API - a powerful vector search and content indexing platform.

Installation

npm install asimov-sdk

Quick Start

import { Asimov } from 'asimov-sdk';

const client = new Asimov({
  apiKey: 'your-api-key-here',
  // Optional: specify a custom base URL
  // baseURL: 'https://your-custom-domain.com',
});

// Search for content
const results = await client.search.query({
  query: 'machine learning',
  limit: 10,
});

console.log(results.results); // Array of search results

// Add content to the index
await client.add.create({
  content: 'Your content here...',
  name: 'Document Name',
  params: {
    category: 'technology',
    author: 'John Doe'
  }
});

API Reference

Initialization

const client = new Asimov(options: AsimovClientOptions)

Options

• apiKey (string, required): Your Asimov API key
• baseURL (string, optional): Base URL for the API (default: https://api.asimov.ai)
• timeout (number, optional): Request timeout in milliseconds (default: 60000)

Search

Search for content using semantic vector search.

const results = await client.search.query(params: SearchParams): Promise<SearchResponse>

SearchParams

• query (string, required): The search query string (min length: 1)
• limit (number, optional): Maximum number of results to return (default: 10, max: 1000)
• id (string, optional): Filter results by document ID
• params (object, optional): Filter results by parameter key-value pairs
• recall (number, optional): Number of candidates for vector search (default: 100, max: 10000)

Note: All parameters are validated using Zod schemas before sending the request.

SearchResponse

{
  success: boolean;
  results: Array<{
    content: string;
  }>;
  count: number;
}

Example

// Basic search
const results = await client.search.query({
  query: 'artificial intelligence',
  limit: 5
});

// Search with filters
const filteredResults = await client.search.query({
  query: 'Python programming',
  limit: 10,
  params: {
    category: 'programming',
    difficulty: 'beginner'
  }
});

// Search specific document
const docResults = await client.search.query({
  query: 'machine learning',
  id: 'doc-123',
  limit: 20
});

Add

Add content to the index for semantic search.

await client.add.create(params: AddParams): Promise<AddResponse>

AddParams

• content (string, required): The content to add to the index (min length: 1, max: 10MB)
• params (object, optional): Parameter key-value pairs for filtering
• name (string, optional): Document name (max length: 500 characters)

Note: All parameters are validated using Zod schemas before sending the request.

AddResponse

{
  success: boolean;
}

Example

// Basic add
await client.add.create({
  content: 'This is a sample document about machine learning...'
});

// Add with metadata
await client.add.create({
  content: 'Advanced neural network architectures...',
  name: 'Neural Networks Guide',
  params: {
    category: 'technology',
    topic: 'deep-learning',
    author: 'Jane Smith'
  }
});

Error Handling

The SDK throws two types of errors:

Validation Errors (ZodError)

Parameters are validated using Zod schemas before making API requests. If validation fails, a ZodError is thrown:

import { Asimov, ZodError } from 'asimov-sdk';

try {
  const results = await client.search.query({
    query: '', // Empty query will fail validation
    limit: 2000 // Exceeds max limit
  });
} catch (error) {
  if (error instanceof ZodError) {
    console.error('Validation Error:', error.errors);
    // Output: [
    //   { path: ['query'], message: 'Query cannot be empty' },
    //   { path: ['limit'], message: 'Limit cannot exceed 1000' }
    // ]
  }
}

API Errors (APIError)

API-related errors are thrown as APIError instances:

import { Asimov, APIError } from 'asimov-sdk';

try {
  const results = await client.search.query({
    query: 'test query'
  });
} catch (error) {
  if (error instanceof APIError) {
    console.error('API Error:', error.message);
    console.error('Status:', error.status);
    console.error('Details:', error.details);
  } else if (error instanceof ZodError) {
    console.error('Validation Error:', error.errors);
  } else {
    console.error('Unexpected error:', error);
  }
}

Complete Error Handling Example

import { Asimov, APIError, ZodError } from 'asimov-sdk';

try {
  const results = await client.search.query({
    query: 'machine learning',
    limit: 10
  });
} catch (error) {
  if (error instanceof ZodError) {
    // Handle validation errors
    console.error('Invalid parameters:', error.errors);
  } else if (error instanceof APIError) {
    // Handle API errors
    console.error('API Error:', error.message);
    console.error('Status Code:', error.status);
  } else {
    // Handle unexpected errors
    console.error('Unexpected error:', error);
  }
}

Using Zod Schemas for Custom Validation

You can import and use the Zod schemas directly for custom validation in your application:

import { SearchParamsSchema, AddParamsSchema } from 'asimov-sdk';

// Validate before using the SDK
const params = {
  query: 'machine learning',
  limit: 10
};

// Safe parse - returns object with success flag
const result = SearchParamsSchema.safeParse(params);
if (result.success) {
  // Use validated params
  const results = await client.search.query(result.data);
} else {
  console.error('Validation errors:', result.error.errors);
}

// Or use parse for direct validation (throws on error)
try {
  const validated = AddParamsSchema.parse({
    content: 'Some content',
    name: 'Document'
  });
  await client.add.create(validated);
} catch (error) {
  // Handle validation error
}

TypeScript Support

The SDK is written in TypeScript and includes full type definitions. Types are automatically inferred from Zod schemas, ensuring type safety at both compile-time and runtime.

License

MIT