Vox Engine JavaScript/TypeScript SDK

The Vox Engine SDK provides a seamless way to interact with Minerva Vox, an AI-powered conversational agent that supports persistent conversations, external API integrations, and dynamic personality settings.

Features

• Real-Time AI Conversations – Send queries and receive AI-generated responses instantly.
• Thread-Based Conversation Management – Maintain persistent conversation threads.
• API Integration – Extend functionality using external services.
• Configurable AI Personalities – Adjust tone, language, and verbosity.
• Secure & Scalable – Uses API keys for authentication.

Installation

Install the package using NPM or Yarn:

npm install @minerva-cloud/vox-sdk

Usage

Initializing the Client

To start using Minerva Vox, create a client instance with your Client ID and API Key:

import { Client } from '@minerva-cloud/vox-sdk';

// Initialize client
const agent = new Client({
  secret: 'YOUR_PROJECT_API_KEY',
  key: 'YOUR_PROJECT_ID',
});

Sending a Query

Interact with Minerva Vox by sending a query:

const response = await agent.interact({
  query: 'Tell me a joke',
});

console.log(response);

Example Response

{
  "status": "success",
  "message": "Why don’t skeletons fight each other? They don’t have the guts!"
}

Handling Multi-Line Responses

Some responses may contain line breaks (\n). You can handle them properly in your display logic:

console.log(response.message.replace(/\n\n/g, '\n').trim());

Example:

Absolutely, here’s another one for you:

What do you call fake spaghetti?

An impasta!

If you’re craving more humor, just say the word!

Customizing the AI Personality

You can modify tone, language, and verbosity for personalized responses.

const response = await agent.interact({
  query: 'Tell me a joke',
  plugins: {
    personality: {
      tone: 'casual',
      language: 'French',
      verbosity: 'low',
    },
  },
});

console.log(response);

API Reference

Client Methods

interact(request: Record<string, any>): Promise<VoxEngineResponse>

Sends a request to Minerva Vox and retrieves an AI-generated response.

Request Parameters

| Field | Type | Required | Description | | ---------- | -------- | -------- | -------------------------------------- | | query | string | ✅ Yes | User's question/query | | threadId | string | ❌ No | Thread ID for conversation continuity | | plugins | object | ❌ No | Optional configuration for AI behavior |

Personality Plugin Options

Customize the AI response style using personality settings inside plugins:

| Field | Type | Default | Description | | ----------- | -------- | -------------- | ------------------------------- | | tone | string | "persuasive" | AI's communication tone | | language | string | "English" | Language of the response | | verbosity | string | "high" | Controls response length/detail |

Example API Request

{
  "query": "What can you do?",
  "threadId": "thread-456",
  "plugins": {
    "personality": {
      "tone": "friendly",
      "language": "English",
      "verbosity": "high"
    }
  }
}

Example API Response

{
  "status": "success",
  "message": "Hi, why don't we start with defining what you need?"
}

Common API Errors

Below are common errors users may encounter and how to resolve them.

| Status Code | Error Type | Resolution | | ----------- | --------------------- | ------------------------------------------------------------------------ | | 401 | Unauthorized | Ensure your API key is valid and included in the Authorization header. | | 404 | Not Found | Verify the clientId and threadId are correct. | | 500 | Internal Server Error | Server-side issue. Contact support if the issue persists. |

Licensing

This project is licensed under the MIT License.

Contact & Support

For issues or feature requests, open a ticket on GitHub.