# EVE - Personal Desktop Assistant

A sophisticated local-first desktop AI assistant with modular personality system, multi-model support, and seamless integration with your development environment.

> **Current Version**: 0.2.0  
> **Status**: ✅ Phase 2 Complete - Enhanced multimodal assistant with voice, files, and system integration

## ✨ Features

### ✅ Implemented (v0.2.0)

- **🤖 Multi-Model AI Chat**
  - Full-featured chat interface with conversation history
  - Support for 15+ latest AI models via OpenRouter
  - Real-time model switching without losing context
  - Adjustable parameters (temperature, max tokens)

- **🎭 Character/Personality System**
  - 6 pre-built AI personalities (Assistant, Creative, Technical, Researcher, Tutor, Casual)
  - Custom character creation with user-defined system prompts
  - First-person conversational style
  - Quick character switching via header dropdown

- **🔐 Local-First Configuration**
  - Automatic API key loading from `.env` file
  - No cloud dependencies for configuration
  - Secure backend key management
  - Smart UI that adapts to available credentials

- **🎨 Modern UI/UX**
  - Clean, responsive interface with dark mode
  - Message formatting with timestamps
  - Conversation management (clear history)
  - Persistent settings across sessions

- **🗣️ Voice Integration (NEW in v0.2.0)**
  - Text-to-Speech with ElevenLabs API and browser fallback
  - Speech-to-Text with Web Speech API (25+ languages)
  - Audio conversation mode for hands-free interaction
  - Per-message voice controls

- **📁 File Attachment Support (NEW in v0.2.0)**
  - Drag & drop file upload
  - Support for images, PDFs, text files, and code
  - Preview thumbnails and content
  - AI can analyze and discuss attached files

- **💾 Conversation Management (NEW in v0.2.0)**
  - Save and load conversations
  - Export to Markdown, JSON, or TXT
  - Search and filter saved conversations
  - Tag and organize conversation history

- **🎨 Advanced Formatting (NEW in v0.2.0)**
  - Markdown with GitHub Flavored Markdown
  - Syntax highlighting for code blocks
  - LaTeX math equation rendering
  - Mermaid diagrams for flowcharts

- **🖥️ System Integration (NEW in v0.2.0)**
  - System tray icon for quick access
  - Global keyboard shortcut (Ctrl+Shift+E / Cmd+Shift+E)
  - Desktop notifications for responses
  - Minimize to tray functionality

### 🚧 Planned Features

See [Roadmap](./docs/planning/ROADMAP.md) for the complete development plan:

- **Phase 3** (Next): Knowledge base, long-term memory, multi-modal capabilities
- **Phase 4**: Developer tools, plugin system, multi-device sync
- **Long-term**: Avatar system, screen/audio monitoring, gaming integration

## Tech Stack

- **Frontend**: React + TypeScript + TailwindCSS
- **Desktop Framework**: Tauri (Rust)
- **Build Tool**: Vite
- **State Management**: Zustand
- **Icons**: Lucide React

## Prerequisites

Before you begin, ensure you have installed:

- **Node.js** (v18 or higher) - [Download](https://nodejs.org/)
- **Rust** (latest stable) - [Install](https://rustup.rs/)
- **npm** or **pnpm** (comes with Node.js)

### Platform-Specific Requirements

#### Linux

**Debian/Ubuntu:**

```bash
sudo apt update
sudo apt install libwebkit2gtk-4.0-dev \
    build-essential \
    curl \
    wget \
    file \
    libssl-dev \
    libgtk-3-dev \
    libayatana-appindicator3-dev \
    librsvg2-dev
```

**Fedora/RHEL:**

```bash
sudo dnf install webkit2gtk4.0-devel \
    openssl-devel \
    curl \
    wget \
    file \
    libappindicator-gtk3-devel \
    librsvg2-devel
```

**Arch:**

```bash
sudo pacman -S webkit2gtk \
    base-devel \
    curl \
    wget \
    file \
    openssl \
    gtk3 \
    libappindicator-gtk3 \
    librsvg
```

#### macOS

```bash
# Xcode Command Line Tools
xcode-select --install
```

#### Windows

- Install [Microsoft C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)
- Install [WebView2](https://developer.microsoft.com/en-us/microsoft-edge/webview2/)

## Quick Start

### Option 1: Automated Setup (Recommended)

Use the setup script to automatically install dependencies:

**Linux/macOS:**
```bash
./setup.sh
```

**Windows:**
```powershell
.\setup.ps1
```

The script will guide you through installing Node.js, Rust, and system dependencies.

### Option 2: Development Scripts

Once setup is complete, use these convenient scripts:

**Start the app:**
```bash
./run.sh        # Linux/macOS
.\run.ps1       # Windows
```

**Stop the app:**
```bash
./kill.sh       # Linux/macOS
.\kill.ps1      # Windows
```

See [SCRIPTS.md](./docs/SCRIPTS.md) for detailed script documentation.

## Getting Started

### 1. Install Dependencies

```bash
# Install Node.js dependencies
npm install

# or if you prefer pnpm
pnpm install
```

### 2. Run Development Server

```bash
# Start the Tauri development server
npm run tauri:dev
```

This will:

- Start the Vite development server
- Compile the Rust backend
- Launch the desktop application with hot-reload

### 3. Build for Production

```bash
# Build the application
npm run tauri:build
```

The compiled application will be in `src-tauri/target/release/`.

## Development Commands

```bash
# Run frontend only (web view)
npm run dev

# Build frontend
npm run build

# Preview production build
npm run preview

# Run Tauri development mode
npm run tauri:dev

# Build Tauri app
npm run tauri:build

# Lint code
npm run lint

# Format code
npm run format
```

## Project Structure

```bash
EVE/
├── src/                    # React frontend source
│   ├── components/         # React components
│   ├── stores/            # Zustand state stores
│   ├── lib/               # Utility libraries
│   ├── App.tsx            # Main app component
│   ├── main.tsx           # Entry point
│   └── index.css          # Global styles
├── src-tauri/             # Rust backend
│   ├── src/
│   │   └── main.rs        # Tauri main entry
│   ├── Cargo.toml         # Rust dependencies
│   └── tauri.conf.json    # Tauri configuration
├── public/                # Static assets
├── docs/                  # Documentation hub (see docs/README.md)
└── package.json           # Node.js dependencies
```

## Configuration

### Environment Variables (Local-First Setup)

EVE is designed for **local-first** usage. Create a `.env` file in the root directory:

```bash
cp .env.example .env
```

Then edit `.env` and add your API keys:

```env
# OpenRouter API Key (required for AI chat)
# Get yours at: https://openrouter.ai/keys
OPENROUTER_API_KEY=sk-or-v1-your-key-here

# ElevenLabs API Key (optional, for future TTS features)
ELEVENLABS_API_KEY=your_api_key_here
```

**Important Notes:**

- Keys are loaded automatically from `.env` on app startup
- No manual configuration needed once `.env` is set up
- Settings UI will show "Key loaded from environment" when keys are detected
- Never commit `.env` files to version control

**Get API Keys:**

- OpenRouter: [https://openrouter.ai/keys](https://openrouter.ai/keys)
- ElevenLabs (optional): [https://elevenlabs.io](https://elevenlabs.io)

## 📚 Documentation

- **[Documentation Index](./docs/README.md)** - Start here for all project documentation
- **[Changelog](./docs/releases/CHANGELOG.md)** - Detailed changelog of all releases
- **[Roadmap](./docs/planning/ROADMAP.md)** - Future features and development plan
- **[Setup Complete](./docs/setup/SETUP_COMPLETE.md)** - Complete setup guide with troubleshooting

## Development Status

### ✅ Phase 1 Complete - Core Foundation (v0.1.0)

All core features are implemented and stable:

- ✅ Desktop application framework (Tauri + React)
- ✅ OpenRouter integration with 15+ AI models
- ✅ Full-featured chat interface
- ✅ Character/personality system with 6 presets + custom
- ✅ Local-first API key management
- ✅ Settings persistence and UI
- ✅ Model parameter controls
- ✅ Linux graphics compatibility fixes
- ✅ Clean, modern UI with dark mode

### ✅ Phase 2 Complete - Enhanced Capabilities (v0.2.0)

All Phase 2 features are production-ready:

- ✅ Voice integration (TTS with ElevenLabs, STT with Web Speech API)
- ✅ File attachment support (images, PDFs, code, text files)
- ✅ Advanced message formatting (syntax highlighting, LaTeX, Mermaid diagrams)
- ✅ System integration (global shortcuts, system tray, notifications)
- ✅ Conversation export and management (Markdown, JSON, TXT)
- ✅ Audio conversation mode for hands-free interaction

### 🚀 Next: Phase 3 - Knowledge Base & Memory (v0.3.0)

Planned features:

- Long-term memory with vector database
- Semantic search across conversations
- Personal knowledge graph
- Document library integration
- Multi-modal capabilities (vision, image generation)

See [Roadmap](./docs/planning/ROADMAP.md) for the complete development plan.

## Contributing

This is currently a personal project. Contributions, suggestions, and feedback are welcome!

## 🛠️ Troubleshooting

### Blank Window on Linux

If the app window opens but remains blank:

- This is a graphics driver compatibility issue
- The project already includes a fix: `WEBKIT_DISABLE_COMPOSITING_MODE=1` in `package.json`
- Restart the app: `npm run tauri:dev`

### API Keys Not Loading

If you see "Configure Settings" on startup despite having a `.env` file:

- Ensure `.env` is in the project root (not in `src-tauri/`)
- Check that keys are named `OPENROUTER_API_KEY` (not `VITE_OPENROUTER_API_KEY`)
- Restart the application after editing `.env`

### Tauri Build Fails

- Ensure Rust is properly installed: `rustc --version`
- Update Rust: `rustup update`
- Install system dependencies (see Prerequisites above)
- Clear Tauri cache: `rm -rf src-tauri/target`

### Node Modules Issues

- Clear node_modules: `rm -rf node_modules package-lock.json`
- Reinstall: `npm install`

### Linux System Dependencies

- Make sure all required packages are installed (see Prerequisites)
- Check WebKit2GTK version: `pkg-config --modversion webkit2gtk-4.0`

For more detailed troubleshooting, see [Setup Complete](./docs/setup/SETUP_COMPLETE.md).

## 📝 License

TBD

## 🤝 Contributing

This is currently a personal project, but contributions, suggestions, and feedback are welcome!

- Report bugs via GitHub Issues
- Suggest features in [Roadmap](./docs/planning/ROADMAP.md)
- Submit pull requests for bug fixes or improvements

---

**Version**: 0.2.0  
**Status**: ✅ Production Ready - Full-featured multimodal AI assistant  
**Last Updated**: October 6, 2025

For detailed changes, see [Changelog](./docs/releases/CHANGELOG.md)