Eleos

Table of Contents

• Eleos
  • Table of Contents
  • Introduction
  • Problem Statement
  • Features
  • Architecture
  • Installation
    • Prerequisites
    • Steps
  • Quick Start Guide
  • Usage Example
    • Running the Playground
  • Testing
    • Running Tests
    • Running Tests in Watch Mode
    • Generating Coverage Reports
    • Sample Test Structure
  • Contributing
  • License

Introduction

Eleos by Emotionality is a sophisticated TypeScript-based system designed to enhance conversational agents with emotional intelligence. Leveraging OpenAI’s API, Eleos analyzes user input to determine emotional context and augments responses with appropriate emotional metadata. This ensures interactions are not only contextually relevant but also empathetically attuned to user sentiments.

Problem Statement

In the realm of conversational AI, generating contextually accurate responses is paramount. However, understanding and appropriately responding to the emotional undertones of user input remains a significant challenge. Traditional chatbots often provide generic responses, lacking the nuanced empathy required for meaningful interactions. Eleos addresses this gap by infusing emotional reasoning into responses, thereby fostering more engaging and supportive user experiences.

Features

• Emotion Classification: Analyzes user input to extract emotional tokens, including sentiment, descriptors, and intensity.
• GPT Integration: Utilizes OpenAI’s GPT-4o to generate contextually appropriate and empathetic responses.
• Response Augmentation: Enhances GPT-generated responses with emotional metadata for clarity and depth.
• Conversation Memory: Maintains a history of interactions to support multi-turn dialogues and context retention.
• Comprehensive Logging: Logs all interactions and processes for monitoring, debugging, and analysis.
• Automated Testing: Ensures reliability and stability through extensive unit and integration tests.
• Continuous Integration: Automates build and test processes using GitHub Actions for seamless development workflows.

Architecture

Eleos follows a modular architecture, promoting scalability and maintainability. The system is divided into distinct components:

1. Emotion Classifier: Determines the emotional context of user input.
2. OpenAI Client: Interfaces with the GPT-4o API to generate responses.
3. Response Augmenter: Enhances GPT responses with emotional metadata.
4. Conversation Memory: Stores conversation history for context-aware interactions.
5. Controllers: Orchestrate the flow between classifiers, clients, and augmenters.
6. Utilities: Provide support functions like environment loading and logging.
7. Testing Suite: Validates each component to ensure system integrity.

Installation

Prerequisites

• Node.js: Version 16.14.0 or higher
• npm: Version 8.0.0 or higher
• OpenAI API Key: Obtain from OpenAI

Steps

1. Clone the Repository

   git clone https://github.com/emotionality/eleos.git
   cd eleos

2. Install Dependencies

   npm install 

3. Set Up Environment Variables Create a .env file in the root directory:

   OPENAI_API_KEY=your_openai_api_key_here

Quick Start Guide

1. Build the Project

   npm run build

2. Run in Development Mode

   npm run dev

   This uses ts-node to execute src/index.ts directly.

3. Run in Production Mode

   npm run start

   Executes the compiled JavaScript from dist/index.js.

4. View Logs

   • Console Output: Real-time logs displayed in the terminal.
   • Log File: Detailed logs appended to src/logs/system.log.

Usage Example

Below is a sample playground.ts demonstrating how to use the Eleos package as an npm module.

// playground.ts

import 'dotenv/config'; // Load environment variables from .env
import { Eleos } from 'eleos'; // Import Eleos from the npm package

(async () => {
  // Initialize Eleos with optional configurations
  const eleos = new Eleos({
    openAIModel: 'gpt-4o', // Optional: Specify the OpenAI model (default is 'gpt-4o')
    logLevel: 'info', // Optional: Set log level ('info' | 'debug' | 'error' | 'silent')
    // customEmotionClassifier: new YourCustomEmotionClassifier(), // Optional: Provide a custom emotion classifier
  });

  // User input
  const userInput = "I'm feeling a bit anxious about tomorrow's meeting.";

  try {
    // Handle user message
    const response = await eleos.handleUserMessage(userInput);
    console.log("BOT =>", response);

    // Optionally, access conversation history
    const history = eleos.getConversationHistory();
    console.log("Conversation History:", history);
  } catch (error) {
    console.error("Error handling user message:", error);
  }
})();

Running the Playground

1. Ensure Dependencies Are Installed

   npm install eleos dotenv ts-node typescript

2. Set Up the .env File

   OPENAI_API_KEY=your_openai_api_key_here

3. Execute the Playground Script

   npx ts-node playground.ts

Testing

Eleos employs Jest for automated testing, ensuring each component functions as intended.

Running Tests

npm test

Running Tests in Watch Mode

npm run test:watch

Generating Coverage Reports

npm run test:coverage

Coverage reports are available in the coverage/ directory.

Sample Test Structure

• Services
  • LocalEmotionClassifier.test.ts
  • OpenAIClient.test.ts
  • ResponseAugmenter.test.ts
• Controllers
  • ConversationController.test.ts
• Utilities
  • Logger.test.ts

Contributing

Contributions are welcome! Please follow these steps to contribute:

1. Fork the Repository
2. Create a New Branch

   git checkout -b feature/YourFeatureName

3. Make Your Changes
4. Commit Your Changes

   git commit -m "Add some feature"

5. Push to the Branch

   git push origin feature/YourFeatureName

6. Open a Pull Request

Please ensure that your code adheres to the project's coding standards and passes all tests.

License

This project is licensed under the MIT License.