npm package: @minerva-cloud/vox-sdk
Description: A typescript client to interact with the Vox Engine service
Author: info@minervacloud.io
Latest version: 1.0.5

# **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**.

![npm](https://img.shields.io/npm/v/@minerva-cloud/vox-sdk)

---

## **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:

```bash
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**:

```typescript
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:

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

console.log(response);
```

#### **Example Response**

```json
{
  "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:

```typescript
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.

```typescript
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**

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

### **Example API Response**

```json
{
  "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](https://github.com/minerva-ai/vox-sdk-js/issues).