aodhan/eve-alpha
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
66749a5ce7e1d24042688fd1db1f78aee87e0750
eve-alpha/README.md
Aodhan Collins 66749a5ce7 Initial commit
2025-10-06 00:33:04 +01:00

8.3 KiB
Raw 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.1.0
Status: ✅ Phase 1 Complete - Core functionality stable and ready to use

✨ Features

✅ Implemented (v0.1.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

🚧 Planned Features

See Roadmap for the complete development plan:

  • Phase 2: Voice integration (TTS/STT), file attachments, advanced formatting
  • Phase 3: Knowledge base, long-term memory, multi-modal capabilities
  • Phase 4: Developer tools, plugin system, multi-device sync

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

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

🚀 Next: Phase 2 - Enhanced Capabilities (v0.2.0)

Planned features:

  • Voice integration (TTS with ElevenLabs, STT)
  • File attachment support
  • Advanced message formatting (code highlighting, LaTeX, diagrams)
  • System integration (keyboard shortcuts, tray icon)
  • Conversation export and management

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.1.0
Status: ✅ Stable - Ready for use
Last Updated: October 5, 2025

For detailed changes, see Changelog