Outworld AI

Outworld AI is a Python-based conversational assistant that integrates Ollama for text generation, Kokoro for text-to-speech (TTS), and an emotion classifier using Hugging Face's transformers. It also manages conversation context history with an SQLite database.

Features

• Text generation using Ollama.
• Emotion classification using transformers (distilbert-base-uncased-emotion).
• Text-to-speech (TTS) with Kokoro for converting responses into audio.
• Conversation history management with SQLite.
• Configurable bot personality and behavior via a JSON configuration file.

---

Installation

Prerequisites

Make sure you have the following installed:

• Python 3.8+
• pip (Python package manager)

Step 1: Clone the Repository

git clone https://github.com/AgapeThelema/Outworld-AI.git
cd Outworld-AI

Step 2: Install Dependencies

pip install -r requirements.txt

For development (to run the automated tests) install the additional tooling:

pip install -r requirements-dev.txt

Step 3: Download NLTK Data

import nltk
nltk.download('punkt')

---

Configuration

Create a bot_config.json file in the project directory with the following structure:

{
  "bot_name": "Outworld",
  "bot_prompt": "You are a friendly AI assistant.",
  "bot_personality": "Helpful and curious.",
  "bot_situation": "Casual conversation."
}

---

Usage

Here’s a basic example to run the bot:

from outworld_ai import OutworldGenerator

# Initialize the Outworld Generator
generator = OutworldGenerator(
    model='llama3.2',
    lang_code='a',
    voice='af_heart',
    speed=1,
    config_path='bot_config.json',
    db_path='context_history.db'
)

# Run the bot
response = generator.run(user_id="12345", user_prompt="Hello, what’s the weather today?")
print("Emotion detected:", response["emotion"]["label"])
print("Generated audio data:", response["audio_data"])
print("Text segments:", response["text_segments"])

Command Line Usage

The project now ships with a simple command line interface:

python -m outworld_ai "Hello there!"

This CLI uses the same configuration and database files as the Python example above.

Running Tests

Install the development requirements and execute:

pytest

Docker

A Dockerfile is provided to make containerised deployments easier:

docker build -t outworld-ai .
docker run --rm outworld-ai

The container prints the CLI help by default. Override the command to run a prompt:

docker run --rm outworld-ai python -m outworld_ai "Hello there!"

Command Line Usage

The project now ships with a simple command line interface:

python -m outworld_ai "Hello there!"

This CLI uses the same configuration and database files as the Python example above.

Running Tests

Install the development requirements and execute:

pytest

Docker

A Dockerfile is provided to make containerised deployments easier:

docker build -t outworld-ai .
docker run --rm outworld-ai

The container prints the CLI help by default. Override the command to run a prompt:

docker run --rm outworld-ai python -m outworld_ai "Hello there!"

---

SQLite Database

The conversation history is stored in an SQLite database (context_history.db), with the following schema:

CREATE TABLE context_history (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id TEXT NOT NULL,
    role TEXT NOT NULL,
    content TEXT NOT NULL,
    timestamp DATETIME DEFAULT CURRENT_TIMESTAMP
);

---

Acknowledgments

• Ollama for text generation.
• Kokoro for text-to-speech conversion.
• Hugging Face for emotion classification.

---

License

This project is licensed under the MIT License. See LICENSE for details.