Lyra/README.md

# Lyra - Advanced AI Discord Chatbot

[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

**Lyra** is a sophisticated AI Discord chatbot with genuine emotional intelligence, self-evolving personality, and human-like conversation capabilities. Unlike traditional chatbots, Lyra learns, adapts, and grows from every interaction, developing unique relationships with users.

> **🤖 AI Development Disclosure**: This project was developed with significant assistance from Claude AI. The architecture, implementation, and documentation were created through human-AI collaboration, representing the cutting edge of AI-assisted software development.

## ✨ Key Features

### 🧠 **Advanced AI Architecture**
- **Self-Evolving Transformer**: Custom neural architecture that adapts based on interactions
- **Behind-the-Scenes Thinking**: Internal dialogue system for genuine, human-like responses
- **CUDA Support**: Optimized for GPU acceleration with 8GB VRAM target

### 🎭 **Sophisticated Personality System**
- **Myers-Briggs + OCEAN Traits**: Comprehensive personality modeling
- **Dynamic Adaptation**: Personality evolves based on interactions and experiences
- **User-Specific Relationships**: Develops unique dynamics with different users
- **Self-Modification**: Can consciously adapt her own personality traits

### ❤️ **Emotional Intelligence**
- **Complex Emotional States**: Multi-dimensional emotions with memory
- **Emotional Expression**: Natural emotional expression in text with human-like inconsistencies
- **Emotional Memory**: Remembers and learns from emotional experiences
- **Contextual Regulation**: Adapts emotional responses to social situations

### 📚 **Ethical Knowledge Acquisition**
- **Project Gutenberg Integration**: Legal acquisition of public domain literature
- **Quality Processing**: Advanced NLP for extracting meaningful knowledge
- **Legal Compliance**: Strict adherence to copyright and ethical guidelines
- **Continuous Learning**: Grows knowledge base through interactions and legal sources

### 🛡️ **Robust Infrastructure**
- **PostgreSQL + Redis**: Scalable data persistence and caching
- **Comprehensive Monitoring**: Learning progress and system health tracking
- **Professional Standards**: Flake8 compliance, comprehensive testing, CI/CD ready

## 🚀 Quick Start

### Prerequisites
- Python 3.9 or higher
- PostgreSQL 12+ (for data persistence)
- Redis 6+ (for caching and real-time data)
- CUDA-capable GPU recommended (8GB+ VRAM)
- Discord Bot Token

### Installation

1. **Clone the repository:**
   ```bash
   git clone https://github.com/yourusername/lyra.git
   cd lyra
   ```

2. **Set up virtual environment:**
   ```bash
   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   ```

3. **Install dependencies:**
   ```bash
   pip install -r requirements.txt
   ```

4. **Set up environment variables:**
   ```bash
   cp .env.example .env
   # Edit .env with your configuration
   ```

5. **Initialize database:**
   ```bash
   python -m lyra.database.init_db
   ```

6. **Run Lyra:**
   ```bash
   python -m lyra.main
   ```

### Configuration

Copy `.env.example` to `.env` and configure:

```bash
# Discord Configuration
DISCORD_TOKEN=your_discord_bot_token_here
DISCORD_GUILD_ID=your_guild_id_here

# Database Configuration
DATABASE_URL=postgresql://user:password@localhost:5432/lyra
REDIS_URL=redis://localhost:6379/0

# Model Configuration (adjust based on your hardware)
MAX_MEMORY_GB=8
HIDDEN_SIZE=768
NUM_LAYERS=12

# Optional: Weights & Biases for training monitoring
WANDB_API_KEY=your_wandb_api_key_here
```

## 🏗️ Architecture Overview

### Core Components

```
lyra/
├── core/                   # Core AI architecture
│   ├── transformer.py      # Self-evolving transformer model
│   ├── attention.py        # Advanced attention mechanisms
│   ├── self_evolution.py   # Continuous adaptation system
│   └── thinking_agent.py   # Behind-the-scenes reasoning
├── personality/            # Personality system
│   ├── matrix.py           # Core personality matrix
│   ├── traits.py           # OCEAN + Myers-Briggs traits
│   └── adaptation.py       # User-specific adaptations
├── emotions/               # Emotional intelligence
│   ├── system.py           # Core emotional system
│   └── expressions.py      # Natural emotional expression
├── knowledge/              # Knowledge acquisition
│   ├── gutenberg_crawler.py # Legal content acquisition
│   └── knowledge_processor.py # NLP processing pipeline
├── database/               # Data persistence
│   ├── models.py           # SQLAlchemy models
│   └── manager.py          # Database operations
└── discord_bot/            # Discord integration
    └── bot.py              # Human-like Discord bot
```

### Self-Evolution Pipeline

1. **Interaction Processing**: Every conversation is analyzed for context, emotion, and success
2. **Personality Adaptation**: Traits evolve based on interaction outcomes
3. **Emotional Learning**: Emotional memories influence future responses
4. **Knowledge Integration**: New information is processed and integrated
5. **Relationship Development**: User-specific adaptations strengthen over time

## 🧪 Development

### Running Tests

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=lyra --cov-report=html

# Run specific test categories
pytest -m "not slow"  # Skip slow tests
pytest -m unit       # Only unit tests
pytest -m integration # Only integration tests
```

### Code Quality

```bash
# Format code
black lyra/ tests/

# Sort imports
isort lyra/ tests/

# Lint code
flake8 lyra/ tests/

# Type checking
mypy lyra/

# Run all checks
pre-commit run --all-files
```

## 🤝 Ethical Considerations

### AI Safety & Alignment
- **Human-Centric Design**: Prioritizes human wellbeing and positive interactions
- **Transparency**: Open about AI nature and capabilities
- **Continuous Monitoring**: Tracks behavior for harmful patterns
- **Fail-Safe Mechanisms**: Multiple layers of safety checks

### Legal & Copyright Compliance
- **Public Domain Only**: Knowledge sources strictly limited to legal content
- **Attribution**: Proper credit for all sources
- **Privacy Respectful**: No storage of private user information
- **Terms of Service**: Respects platform terms and conditions

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- **Claude AI**: Significant architectural and implementation assistance
- **Project Gutenberg**: Public domain content for ethical knowledge acquisition
- **Hugging Face**: Transformer models and NLP tools
- **Discord.py**: Excellent Discord API wrapper
- **PyTorch Community**: Foundation ML framework

---

**⚠️ Important**: Lyra is an experimental AI system. While designed with safety in mind, please use responsibly and maintain appropriate human oversight.

**🤖 AI Collaboration**: This project showcases the potential of human-AI collaboration in software development. The entire system was designed and implemented with Claude AI assistance.