NOVA-AI

NOVA AI — Complete Setup & User Guide

Welcome to NOVA AI, a modular, high-performance AI assistant workstation. NOVA AI gives you complete freedom to run local AI models privately on your computer without external dependencies, connect to Ollama, or use cloud models like GPT-4o, Claude 3.5, and Gemini.

1. System Requirements

Specification	Minimum	Recommended
OS	Windows 10/11 (64-bit), macOS 12+, Linux	Windows 11 (64-bit) / macOS / Ubuntu
RAM	4 GB	16 GB+
Storage	1 GB (App only)	10 GB+ (for local model weights)
GPU (Optional)	Integrated graphics / CPU only	NVIDIA GPU with CUDA or Apple Silicon (Metal)

For building from source you also need:

Tool	Version	Needed for
Node.js	18+ (CI uses 22)	Building the web UI (`frontend/`), desktop app (Tauri 2), and browser extension
Rust	1.90+	Building the native `nova_ai_rust` extension (`rustup` reads `rust/rust-toolchain.toml` automatically)
uv	latest	Fast dependency management (`uv sync`); auto-installed by the installers
Ollama	latest	Local models via Ollama (optional — in-process GGUF works without it)
Tesseract OCR	5.x	`nova screen` OCR on Windows (UB-Mannheim build)

2. Installation Methods

Choose the method that best fits your environment:

Method A: Standalone Windows Executable (Easiest)

No Python, Node.js, or external runtimes required.

Option 1 — Desktop Installer (recommended):

Download NOVA.AI_1.2.14_x64-setup.exe from the Releases page.
Run it — installs the NOVA AI desktop app per-user (no admin required), with Start Menu / Desktop shortcuts.
Launch NOVA AI from the Start Menu. For the self-contained CLI/backend without Python, use the portable zip (Option 2).

The installer bundles the Quick Capture popup (press Alt+Space anywhere on Windows), the dev-watch diagnostics CLI, and morning digest notifications — no extra setup needed.

Option 2 — Portable ZIP:

Download nova-ai-windows-x64.zip from the Releases page.
Extract the .zip archive to a folder of your choice (e.g. C:\Program Files\NOVA AI or D:\NOVA AI).
Double-click nova-ai-windows-x64.exe or launch it via PowerShell / Command Prompt:
```
.\nova-ai-windows-x64.exe serve
```
Open your browser to: http://localhost:8000

Method B: Python Package via Pip

Recommended for Python users and cross-platform environments.

Make sure Python 3.10+ is installed on your system.
Open your terminal and install NOVA AI:
```
pip install nova-ai-pro
```
(Optional) Install in-process GGUF engine support:
```
pip install "nova-ai-pro[inference-gguf]"
```
Start NOVA AI:
```
nova serve
```
Open your browser to: http://localhost:8000

Method C: Developer Source Install

For modifying source code and contributing.

Prerequisites: Python 3.10–3.13, Git, Node.js 18+ (to build the web UI), and either uv (install guide) or plain pip. Rust 1.90+ is optional — it is only needed to build the native nova_ai_rust extension locally (rustup picks the right toolchain from rust/rust-toolchain.toml automatically).

Clone the repository:

git clone https://github.com/Hamza35779/NOVA-AI.git
cd NOVA-AI

Create and activate a virtual environment:

# With uv (recommended — creates .venv for you):
uv sync --extra server --extra tools-search --extra inference-gguf
.venv\Scripts\activate      # Windows (PowerShell: .venv\Scripts\Activate.ps1)
source .venv/bin/activate    # macOS / Linux

# Or with plain pip:
python -m venv .venv
.venv\Scripts\activate      # Windows (PowerShell: .venv\Scripts\Activate.ps1)
source .venv/bin/activate    # macOS / Linux
pip install -e ".[server,tools-search,inference-gguf]"

(Recommended) Build the native Rust extension — some memory/server APIs require it:
```
uv run maturin develop --manifest-path rust/crates/nova_ai-python/Cargo.toml
```
Build the web frontend (the built UI is generated, not committed — nova serve needs it to show the web app):
```
cd frontend
npm install
npm run build
cd ..
```
If you skip this step the API still works, but http://localhost:8000 will show a “web UI hasn’t been built” page with these same instructions.
Start the development server:
```
nova serve
```
Open http://localhost:8000 and run nova doctor to verify your installation.

Prefer zero manual steps? ./scripts/quickstart.sh (macOS/Linux) automates all of the above — including installing uv and Ollama and pulling a starter model — then opens the UI in your browser. On Windows, run install.bat.

A prebuilt Windows setup EXE and portable ZIP are available on the Releases page — see Method A. For PowerShell deployment without WSL, see deploy/windows/README.md.

3. Starting NOVA AI

Starting the Web UI Server

# Default (port 8000)
nova serve

# Custom host and port
nova serve --host 0.0.0.0 --port 8080

Running as a Background Daemon

nova start      # Starts server in background
nova status     # Checks if server is running
nova stop       # Stops the server
nova restart    # Restarts the server

4. Managing & Running Models

NOVA AI gives you full flexibility in choosing how to run models:

┌─────────────────────────────────────────────────────────────┐
│                       NOVA AI Engine                        │
├─────────────────┬─────────────────────┬─────────────────────┤
│  1. In-Process  │  2. Local Ollama    │  3. Cloud APIs      │
│     GGUF        │     Integration     │     (OpenAI/Claude) │
│  (100% Offline) │  (Local Server)     │  (High Capability)  │
└─────────────────┴─────────────────────┴─────────────────────┘

Option 1: In-Process GGUF Models (100% Free, No Ollama)

No setup, zero configuration, works out of the box.

Open NOVA AI in your browser (http://localhost:8000).
Click GGUF Hub (No Ollama) in the sidebar (/gguf-hub).
Browse the curated catalog (e.g. Qwen 2.5, Llama 3.2, Phi-4 Mini, DeepSeek-R1, Mistral).
Click Download & Install.
Watch the live progress bar download directly from Hugging Face into ~/.nova_ai/models/.
Once complete, the model immediately appears in the chat model picker!

Manual GGUF Import: You can also drop any .gguf file downloaded from Hugging Face directly into your models folder. NOVA AI will auto-detect it.

OS Models folder

Windows %USERPROFILE%\.nova_ai\models\ (e.g. C:\Users\<YourUsername>\.nova_ai\models\)

Linux / macOS ~/.nova_ai/models/

OS	Models folder
Windows	`%USERPROFILE%\.nova_ai\models\` (e.g. `C:\Users\<YourUsername>\.nova_ai\models\`)
Linux / macOS	`~/.nova_ai/models/`

Option 2: Ollama Local Models

If you already use Ollama.

Install and run Ollama:
```
ollama serve
```
Pull any model in your terminal:
```
ollama pull qwen2.5:7b
```
or use the in-app Model Hub (Ollama) tab (/model-hub) to download models directly.
NOVA AI automatically detects running Ollama models and adds them to your dropdown.

Option 3: Cloud Models

For cloud-scale reasoning and vision models.

Navigate to Settings (/settings) in the web UI.
Enter your API key(s) for your desired provider:
- OpenAI: OPENAI_API_KEY (e.g. gpt-4o, gpt-4o-mini, o3-mini)
- Anthropic: ANTHROPIC_API_KEY (e.g. claude-3-5-sonnet)
- Google Gemini: GEMINI_API_KEY (e.g. gemini-2.0-flash, gemini-1.5-pro)
- Groq: GROQ_API_KEY (e.g. llama-3.3-70b-versatile)
Select any cloud model from the top-bar dropdown.

5. Core Features & Usage Modes

Web Workstation UI

Chat Interface: Multi-turn conversations with code syntax highlighting, copy-to-clipboard, markdown formatting, and LaTeX math rendering.
Model Compare Mode (/compare): Send a single prompt simultaneously to two different models side-by-side to compare latency, token speed, and answer quality.
Personas (/personas): Switch between custom assistant personas (e.g., Senior Software Architect, Research Scientist, Technical Writer).

Command-Line Interface (CLI)

NOVA AI includes command-line tools for quick terminal workflows:

1. Quick Question (`nova ask`)

nova ask "Explain how vector embeddings work in two sentences"

2. Terminal Interactive Chat (`nova chat`)

nova chat

3. Clipboard AI (`nova clip`)

Summarize or translate whatever is currently in your system clipboard:

nova clip summarize
nova clip translate --to spanish
nova clip explain-code

4. Diagnostic Doctor (`nova doctor`)

Verify your system dependencies, GPUs, and engine health:

nova doctor

Voice Mode & Wake-Word Detection

Engage in hands-free voice conversations with NOVA AI:

# Push-to-talk voice mode
nova voice

# Hands-free wake-word mode (activates when you say "hey nova")
nova voice --wake-word "hey nova"

Instant AI access from anywhere without switching windows:

Windows: press Alt+Space — a compact, frameless chat popup appears centered on screen.
macOS: press Cmd+Shift+Space for the native panel.
Type a question, get a streaming answer, press Escape (or click elsewhere) to dismiss.
The popup’s conversation is saved and synced back into the main app automatically, so nothing you ask in the popup is lost.

The popup talks to the local backend (http://127.0.0.1:8000) — start NOVA AI first.

Morning Digest & Notifications

The scheduled morning briefing now tells you when it’s ready:

When a digest is generated (via scheduler, CLI, or server), a desktop notification fires with the briefing’s opening line — click it to open the digest player.
nova digest plays the audio on Windows natively (.wav via winsound; .mp3 opens in your default media player).

nova digest --fresh    # generate + play your briefing

Build Diagnostics (nova dev-watch)

Run a build or test command and let NOVA AI diagnose the failures:

# Run once; on failure, print a self-healing fix suggestion
nova dev-watch -c "pytest -q"

# Keep re-running every 60 seconds (Ctrl+C to stop)
nova dev-watch -c "cargo build" --watch --interval 60

# Let the agent apply fixes, not just suggest them
nova dev-watch -c "npx tsc -b" --on-failure fix

Failures are classified as timeout, exit_code, or error_output (zero-exit runs that embed tracebacks are caught too).
Suggestions come from the self_healing_react agent and appear in the terminal panel.
Every run is reported to the local server and shown live in the Build Diagnostics panel on the Dashboard (pass/fail history, exit codes, expandable suggestions).

Task Planner & Workflow Execution

Break down complex objectives into Directed Acyclic Graph (DAG) task plans with dependency resolution:

In the Web UI or via API (/api/tasks), enter a high-level goal.
The planner breaks the goal into sequential and parallel subtasks.
Real-time progress updates are streamed live as each task executes.

Interactive Canvas Artifacts

Generate dynamic HTML, CSS, React widgets, SVG diagrams, and visualizations directly inside your conversation:

Ask NOVA AI to “Create an interactive ROI calculator widget” or “Render an architecture diagram in Canvas”.
An interactive sandboxed preview renders directly inline inside the chat.

Deep Research & Web Search

Perform multi-source web investigations with real-time fact synthesis:

nova ask --research "Summarize latest quantum computing milestones this month"

Memory Wiki Knowledge Base

Build an evolving, long-term personal knowledge base:

# Inspect stored knowledge entities
nova memory-wiki list

# Search knowledge base
nova memory-wiki search "API architecture patterns"

6. Troubleshooting & Common Questions

Q: Port 8000 is already in use

Solution: Specify an alternate port with --port:

nova serve --port 8080

Q: Model runs slowly on my machine

Solution:

Use smaller quantized models such as Qwen 2.5 0.5B / 1.5B or Phi-4 Mini 3.8B.

For GPU acceleration with GGUF models on NVIDIA systems, reinstall llama-cpp-python with CUDA:

pip install llama-cpp-python --upgrade --force-reinstall --no-cache-dir --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu124

Q: The web page at http://localhost:8000 shows “The web UI hasn’t been built yet”

Solution: From a source checkout the browser UI is generated, not committed. Build it once, then restart the server:

cd frontend && npm install && npm run build
cd ..
nova serve

nova doctor warns when it’s missing.

Q: `nova serve` says “Binding to 0.0.0.0 requires an API key”

Solution: Either run local-only (recommended to start):

nova serve --host 127.0.0.1
# or set host = "127.0.0.1" under [server] in ~/.nova_ai/config.toml

or, if you really want LAN access, keep host = "0.0.0.0" and run nova auth create-key.

Q: `nova init` overwrote my config — can I get it back?

Solution: Yes. Since this version, nova init saves the previous file as ~/.nova_ai/config.toml.bak-<timestamp> (keeps the last 5). Copy the newest one back.

Q: My config is broken and nothing starts — how do I start fresh?