Metadata-Version: 2.2
Name: minerva_cloud_vox_sdk
Version: 1.0.7
Summary: Python client for Vox Engine Service
Home-page: https://github.com/house-of-minerva/minerva_vox_sdk-py
Author: Ricardo Arcifa
Author-email: rarcifa@gmail.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: summary

# **Vox Engine Python SDK**

The **Vox Engine Python SDK** provides a seamless way to interact with the **Vox Engine Service**, enabling developers to integrate AI-powered conversational agents with persistent cloud storage, API integrations, and structured thread management.

![PyPI](https://img.shields.io/pypi/v/minerva_cloud_vox_sdk)  
![Python](https://img.shields.io/pypi/pyversions/minerva_cloud_vox_sdk)

---

## **Features**

- **Real-Time AI Conversations** – Send queries and get AI-generated responses instantly.
- **Thread-Based Conversation Management** – Maintain persistent conversation threads.
- **Cloud Storage Integration** – Store interactions across multiple sessions.
- **External API Integration** – Seamlessly connect with external services.
- **Configurable AI Personalities** – Adjust tone, language, and verbosity.
- **Scalable & Secure** – Uses API keys and authentication for secure requests.

---

## **Installation**

To install the package, run:

```bash
pip install minerva_cloud_vox_sdk
```

---

## **Usage**

### **Initializing the Client**

To use Minerva Vox, create a client instance with your **Project ID** and **API Key**:

```python
from minerva_cloud_vox_sdk import Client

# Initialize client
agent = Client(
    key="YOUR_PROJECT_ID",
    secret="YOUR_API_KEY"
)
```

---

### **Sending a Query**

Interact with Vox by sending a query:

```python
response = agent.interact({
    "query": "Tell me a joke"
})

print(response)
```

#### **Example Response:**

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

---

### **Customizing the AI Personality**

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

```python
response = agent.interact({
    "query": "Tell me a joke",
    "plugins": {
        "personality": {
            "tone": "casual",
            "language": "French",
            "verbosity": "low"
        }
    }
})

print(response)
```

---

## **API Reference**

### **Client Methods**

- `interact(request: dict) -> dict`:  
  Sends a request to Minerva Vox and retrieves an AI-generated response.

### **Request Parameters**

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

### **Personality Plugin Options**

Customize the AI response style using **personality settings** inside `plugins`:

| Field       | Type  | Default        | Description                     |
| ----------- | ----- | -------------- | ------------------------------- |
| `tone`      | `str` | `"persuasive"` | AI's communication tone         |
| `language`  | `str` | `"English"`    | Language of the response        |
| `verbosity` | `str` | `"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",
  "response": "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 `projectId` 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-engine-client-py/issues).
