aodhan/eve-alpha
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
eve-alpha/README.md
Aodhan Collins 8d6a681baa Phase 2 complete.
2025-10-06 21:08:25 +01:00

10 KiB
Raw Permalink Blame History

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 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
  • Rust (latest stable) - Install
  • npm or pnpm (comes with Node.js)

Platform-Specific Requirements

Linux

Debian/Ubuntu:

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:

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

Arch:

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

macOS

# Xcode Command Line Tools
xcode-select --install

Windows

Quick Start

Option 1: Automated Setup (Recommended)

Use the setup script to automatically install dependencies:

Linux/macOS:

./setup.sh

Windows:

.\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:

./run.sh        # Linux/macOS
.\run.ps1       # Windows

Stop the app:

./kill.sh       # Linux/macOS
.\kill.ps1      # Windows

See SCRIPTS.md for detailed script documentation.

Getting Started

1. Install Dependencies

# Install Node.js dependencies
npm install

# or if you prefer pnpm
pnpm install

2. Run Development Server

# 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

# Build the application
npm run tauri:build

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

Development Commands

# 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

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:

cp .env.example .env

Then edit .env and add your API keys:

# 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:

📚 Documentation

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 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.

📝 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
  • 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