# NovaAvatar - Installation Guide

## System Requirements
- macOS 10.13 (High Sierra) or later
- Apple Silicon or Intel Mac
- 8GB RAM minimum (16GB recommended)

## Installation

1. **Download** NovaAvatar.zip
2. **Extract** the zip file by double-clicking it
3. **Move** NovaAvatar.app to your Applications folder (optional but recommended)
4. **First Launch**: 
   - Right-click on NovaAvatar.app
   - Select "Open" from the menu
   - Click "Open" when the security warning appears
   - This is only needed the first time!

## Important: First Launch Security Warning

Since this app is not signed with an Apple Developer certificate, macOS will show a security warning the first time you open it.

**To bypass this:**
1. Right-click (or Control-click) on NovaAvatar.app
2. Choose "Open" from the menu
3. Click "Open" in the dialog that appears

After the first launch, you can open it normally by double-clicking.

## Features

- **GUI Interface**: Easy-to-use chat interface
- **Local LLM**: Powered by OpenHermes 2.5 Mistral 7B
- **Document Support**: Load and chat with your documents (.txt, .md, .docx)
- **Text-to-Speech**: High-quality voice synthesis (optional, requires Python - see limitations below)
- **Private**: Everything runs locally on your Mac

## Known Limitation: Text-to-Speech

TTS currently only works when launching from Terminal. This will be fixed in future versions.

**To use TTS in this demo:**
1. Install Python 3.12+ and kokoro-tts (see "Enabling Text-to-Speech" section below)
2. Open Terminal (Applications → Utilities → Terminal)
3. Run: `open /Applications/NovaAvatar.app`
4. TTS will now work

**Or** just use the app without TTS - all other features (chat, document reading) work perfectly when double-clicked from Finder.

## Performance Notes

- **First launch** may take 10-20 seconds to load the model
- **Initial response** may show a loading indicator while generating - this is normal
- **Response time** depends on your Mac's processor
  - Apple Silicon (M1/M2/M3/M4): Fast responses
  - Intel Macs: Slower but functional
- **Large bundle size** (4-5GB) includes the AI model and all dependencies

## Enabling Text-to-Speech (Optional)

NovaAvatar includes text-to-speech support, but it requires Python and the Kokoro TTS package to be installed on your Mac.

### Installation Steps:

**1. Install Python 3.12 or later**

Check if you already have Python:
```bash
python3 --version
```

If you don't have Python or it's older than 3.12, download from: https://www.python.org/downloads/

**2. Install Kokoro TTS**

Open Terminal (Applications → Utilities → Terminal) and run:
```bash
pip3 install kokoro-tts
```

Wait for the installation to complete (this may take a few minutes).

**3. Verify Installation**

Test that kokoro-tts is installed:
```bash
kokoro-tts --help
```

If you see help text, you're all set!

**4. Restart NovaAvatar**

Close NovaAvatar completely and reopen it. Text-to-speech should now work automatically.

### Troubleshooting TTS

**"command not found: pip3"**
- Install Python from python.org first

**"command not found: kokoro-tts"**
- Try: `python3 -m pip install kokoro-tts`
- Or check if it's installed in a different location: `python3 -m pip show kokoro-tts`

**TTS still doesn't work after installing**
- Make sure you completely quit NovaAvatar (Cmd+Q)
- Open Terminal and run: `which kokoro-tts` to verify it's in your PATH
- Try launching NovaAvatar from Terminal: `open /Applications/NovaAvatar.app`

### Note About TTS from Finder

Text-to-speech works best when launching NovaAvatar from Terminal or after properly installing kokoro-tts system-wide. If you double-click the app from Finder and TTS doesn't work, this is normal - the app will still function perfectly for chat without voice.

### App won't open
- Make sure you used "Right-click → Open" the first time
- Check System Preferences → Security & Privacy for any blocks

### App is slow
- This is normal for local AI - responses take 10-60 seconds depending on your hardware
- Close other applications to free up RAM
- The AI model is running entirely on your computer (no internet needed!)

### "Damaged app" error
- This happens if the download was corrupted
- Re-download NovaAvatar.zip and try again

## Support

For issues, questions, or feedback, contact: **yusifia17@gmail.com**

## License

---

**Note**: This application processes everything locally on your computer. No data is sent to external servers.