402 lines
10 KiB
Markdown
402 lines
10 KiB
Markdown
# 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)
|