openElara - AI Companion Platform

openElara is a desktop AI assistant built with Electron, Python, and advanced RAG (Retrieval-Augmented Generation) capabilities. Chat with multi-modal AI companions, generate images and videos, perform web research, and manage your personal knowledge base - all from a single application.

---

Quick Start

Prerequisites

• Node.js 16+ and npm
• Python 3.11+ (recommend using venv)
• Free API Key from Together.ai (required for basic functionality)

Installation

See INSTALLATION_GUIDE.md for complete setup instructions.

Essential Steps:

1. Install Node.js dependencies: npm install
2. Set up Python environment: cd backend && python -m venv venv311 && venv311\Scripts\activate
3. Install Python packages: pip install -r requirements.txt
4. Add Together.ai API key in Account Settings
5. Launch app: npm start

Required Python Packages

Core ML Stack (see backend/requirements.txt for full list):

• numpy>=2.0.0 - NumPy 2.x with modern dtype handling
• torch>=2.5.0 - PyTorch for embeddings and ML models
• transformers>=4.40.0 - Hugging Face transformers library
• sentence-transformers>=3.0.0 - Semantic embeddings (device-aware)
• faiss-cpu>=1.8.0 - REQUIRED for RAG and emotional intelligence features
• chromadb~=0.5.0 - Vector database for knowledge management
• together>=1.2.0 - Together.ai SDK for LLM/embedding API access
• exa-py>=1.0.0 - REQUIRED for Power Knowledge (Exa.ai) search
• langchain>=0.2.0 - LLM orchestration framework

⚠️ Migration Notes: If upgrading from earlier versions, see devdocs/10_DEPENDENCY_STRATEGY.md for breaking change guidance (NumPy 2.0, Together 1.x SDK, sentence-transformers 3.x).

---

Features

🤖 Multi-Character AI Companions

Four unique AI personalities with distinct voices, visual descriptions, and conversation styles:

• Elara (Default) - Playful, adventurous, creative problem-solver
• Aeron - Strategic guardian, protective wisdom
• Aelira - Philosophical muse, intellectual challenger
• Andros - Pragmatic business/tech advisor

🧠 Advanced RAG System

3-Layer Context Injection:

1. Recent Turns - Guaranteed n most recent conversations (chronological)
2. Semantic History - Relevant past conversations (similarity search)
3. Knowledge Base - Content from ingested documents (PDF, DOCX, TXT, MD)

Emotional Intelligence (Optional):

• Populate emotional context database with collect_emotions.py
• Uses Exa.ai search to gather emotional understanding
• Enhances empathy and contextual awareness in responses

🎨 AI Content Generation

• Images: Flux.1, FLUX 1.1 Pro, Stable Diffusion models via Together.ai/FAL.ai
• Videos: Minimax, Luma, Kling, Runway Gen-3 via FAL.ai/Replicate
• Theme System: AI-generated Tailwind CSS themes (light/dark modes)

🔍 Power Knowledge (Exa.ai)

Semantic web search with AI-curated results. Automatically formats research into structured Markdown files saved to Output/exa/.

📄 Document Processing

Supported Formats: PDF (with OCR), DOCX, TXT, MD, HTML
Capabilities: Table extraction, image OCR, recursive folder ingestion
Output: Markdown conversion for RAG ingestion

🕷️ Web Scraping

Scrapy integration for structured web data extraction. Results saved to Output/scrapy/.

🔐 Content Protection

• Digital Signing: Cryptographic signatures for generated content
• Watermarking: C2PA metadata embedding for provenance tracking
• Viewer Tool: Inspect signatures and watermarks on files

---

Architecture

Technology Stack

• Frontend: Electron (Chromium + Node.js), Tailwind CSS (migrating from Bootstrap)
• Backend: Python 3.11+, ChromaDB vector database
• LLM Providers: Ollama (local), Together.ai, OpenRouter, OpenAI-compatible APIs
• Storage: electron-store (settings), safeStorage (encrypted API keys)

Key Components

• RAG Backend (backend/rag_backend.py) - ChromaDB operations, context injection
• Emotional RAG (backend/collect_emotions.py) - Emotional database population via Exa.ai
• Embedding Service (backend/embedding_service.py) - Together.ai/Local embeddings
• Ingestion Pipeline (backend/ingestion_orchestrator.py) - Document processing
• IPC Handlers (src/main/handlers/) - Main process operations
• Character System (src/main/characters/) - AI companion definitions

Data Flow

User Input → Renderer (renderer.js, appHandlers.js)
          ↓
Token Budget Calculation (tokenManager.js)
          ↓
RAG Context Injection (apiHandlers.js → rag_backend.py)
  - get_recent_turns() → Recent conversations
  - search() → Semantic history + knowledge base
          ↓
API Routing → Provider handlers (Ollama/Together/OpenRouter)
          ↓
Response Streaming → UI Update → Save to RAG

---

API Keys & Services

Required

• Together.ai - Free tier available, required for embeddings and LLM access

Optional (Enable Specific Features)

• OpenRouter - Access to 100+ LLM models
• Exa.ai - Power Knowledge semantic web search (required for collect_emotions.py)
• FAL.ai - Advanced image/video generation models
• Replicate - Video generation (Runway, Kling)
• Anthropic/OpenAI - Direct API access (if not using Together/OpenRouter)

All keys stored encrypted via Electron's safeStorage. Add keys in Account Settings.

---

File Locations

User Data (Windows)

• Config: %AppData%\Roaming\openelara\config.json
• Database: %AppData%\Roaming\openelara\db\ (ChromaDB collections)
• Outputs: %AppData%\Roaming\openelara\Output\
  • exa/ - Research results
  • scrapy/ - Web scraping data
  • images/ - Generated images
  • videos/ - Generated videos

Project Structure

See docs/PROJECT_STRUCTURE.md for complete directory map.

---

Documentation

• Installation Guide - Complete setup instructions
• User Manual - Feature documentation
• API Quick Reference - IPC handlers and Python scripts
• Custom Model Payloads - Advanced API configuration
• Digital Signing Setup - Content authentication
• Tailwind Migration Plan - Bootstrap → Tailwind CSS roadmap
• Dependency Strategy - Python package modernization plan

Developer Documentation

See devdocs/ folder for architecture details, implementation specs, and migration guides.

---

Troubleshooting

"ModuleNotFoundError: No module named 'faiss'"

Solution: Install missing package in Python environment:

cd backend
venv311\Scripts\activate
pip install faiss-cpu exa-py

RAG Features Not Working

Causes: Missing faiss-cpu or exa-py packages
Solution: Install as above, restart app

"Multiple venv folders?"

• venv311 is the active Python environment (use this)
• venv (if exists) is likely a duplicate - safe to delete

Dependency Upgrade Issues

If upgrading to latest requirements.txt versions (NumPy 2.0, Together 1.x, sentence-transformers 3.x):

• See devdocs/10_DEPENDENCY_STRATEGY.md for breaking change analysis
• Code refactoring required in: together_provider.py, local_embedding_model.py, chromadb_faiss.py

---

Contributing

1. Fork the repository
2. Create feature branch: git checkout -b feature/your-feature
3. Follow existing code style (see .github/instructions/COPILOT_INSTRUCTIONS.md)
4. Test thoroughly (especially RAG ingestion and character switching)
5. Submit pull request

---

License

See LICENSE file for details.

---

Support

For issues, feature requests, or questions:

• Review documentation in docs/ folder
• Check devdocs/ for technical architecture details
• Ingest documentation into RAG knowledge base for in-app help