NexusOS/README.md

<div align="center">

<img src="assets/gitnexus-logo.svg" alt="NexusOS" width="96">

# NexusOS

**A local-first AI assistant platform.** Runs entirely on your machine — a
Python/FastAPI backend, a bundled Ollama instance for inference, a persistent
memory service, and a React frontend. No external AI provider is called.

</div>

---

## What it is

NexusOS ("Nexus") is a self-hosted assistant you actually own. All inference
runs through a **locally bundled Ollama** on `localhost`; conversations, facts,
and settings live in local SQLite. It ships with desktop branding (XFCE theme,
icons, boot splash) so it can be run as a full assistant environment, not just
a web app.

- **Chat** — streaming responses from local Ollama models (SSE).
- **Persistent memory** — a dedicated service auto-extracts durable facts from
  each exchange and layers them into future prompts.
- **Playbooks** — ordered YAML system-prompt records; the first is the active
  persona, the rest are injected as reference context.
- **Model management** — list, pull, and delete Ollama models from the UI/CLI.
- **History** — full conversation persistence, search, edit, export.

## Quick start

NexusOS runs **single-process**: the backend on `:8000` serves the built web UI
itself, so there's no separate frontend server at runtime. Ollama is started
manually from the app (**Start AI** in the sidebar), not at boot.

### Windows (recommended)

```powershell
# 1. Install Git, then clone (Gitea user + PAT):
winget install Git.Git
# open a NEW PowerShell window, then:
git clone https://git.enderofwings.com/enderofwings/NexusOS.git nexus-core
cd nexus-core

# 2. Native install — winget Python/Node/Ollama, venv, pip, web build, desktop icon
powershell -ExecutionPolicy Bypass -File .\install-windows.ps1
```

> **Execution policy:** Windows blocks unsigned `.ps1` scripts by default, so
> run them with `-ExecutionPolicy Bypass` as shown (a one-run override — nothing
> permanent). Double-clicking `install-windows.ps1` or running `.\install-windows.ps1`
> bare will fail with *"running scripts is disabled on this system"*.
> The installer self-elevates (a UAC prompt will appear).
>
> To allow scripts persistently instead (then you can run `.\...ps1` directly):
> ```powershell
> Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
> ```

Then double-click the **NexusOS** desktop icon (the shortcut already passes the
bypass), or launch from a shell with:

```powershell
powershell -ExecutionPolicy Bypass -File .\launch_nexus.ps1
```

The app opens at `:8000`; click **Start AI** to launch Ollama. The installer
uses `requirements-wsl.txt` (CPU-only, pure-Python — no ML stack, since Ollama
does all inference over HTTP).

### Linux

```bash
# 1. Install deps into the Promethean venv (auto-selects AMD/NVIDIA/CPU)
./bin/install.sh

# 2. Launch (memory :8001, backend :8000 — backend also serves the built UI)
./launch_nexus.sh
```

Python deps are layered: `requirements-base.txt` (GPU-agnostic core) plus one
GPU overlay — `requirements-amd.txt` (ROCm) or `requirements-nvidia.txt` (CUDA).
`requirements-wsl.txt` is the standalone CPU-only runtime (no base overlay).
`bin/install.sh` picks the right one for the host.

### Individual services

```bash
source Promethean/bin/activate

uvicorn synapse.main:sio_app          --host 0.0.0.0 --port 8000 --reload   # backend (serves the UI too)
uvicorn synapse.memory.service:app    --host 0.0.0.0 --port 8001 --reload   # memory

# Frontend dev server (hot-reload) — only needed when editing the UI;
# production serves the built dist/ from the backend at :8000.
cd interface/web && npm run dev
```

## CLI (`ncp`)

Start/stop services and drive the same features as the web UI over the REST API:

```bash
./management/nexus-cli.sh start        # backend + frontend (--backend|--frontend|--memory)
./management/nexus-cli.sh stop

ncp chat "<message>"                   # stream a reply
ncp memory list | add <text> | rm <id>
ncp playbook list | show <id>          # first playbook (*) = active system prompt
ncp history [query]                    # recent conversations
```

## Architecture

| Component | Location | Role |
|---|---|---|
| **Synapse** (backend) | `synapse/` | FastAPI app. `/chat/stream`, `/playbooks`, `/memory`, `/models`, `/conversations`, `/settings`, `/ollama`, `/icons`. Assembles the system prompt: active playbook → reference playbooks → memory facts → relevant past snippets. |
| **Memory service** | `synapse/memory/` | Separate FastAPI app (:8001). `/memories/extract` uses an Ollama prompt to decide what to persist. Shares the SQLite DB with the backend. |
| **Playbooks** | `synapse/playbooks/` + `data/playbooks/` | Ordered `{id}.yaml` records managed by `PlaybookManager`. |
| **Ollama** | `ollama/bin/ollama` | Bundled binary; `OllamaManager` handles lifecycle + model selection (Vulkan GPU detection). HTTP API at `127.0.0.1:11434`. |
| **Frontend** | `interface/web/` | React 19 + Vite. Built to `dist/` and served by the backend at `:8000` (single-process). Pages: Chat, Playbooks, History, Models, Memory, Settings. |

### Storage

Most data lives in `synapse/memory/memory.db` (SQLite, WAL) — facts,
conversations, messages, settings. Playbooks are the exception (YAML files in
`data/playbooks/`). All paths are defined in `synapse/nexus_config.py`.

## Layout

```
synapse/          FastAPI backend + memory service + playbook/ollama managers
interface/web/    React + Vite frontend
management/       nexus-cli.sh, ncp API client, control panel, desktop theme
bin/              install, backup/restore, panel + provisioning scripts
assets/           branding: icons, boot splash, XFCE/GTK theme
data/playbooks/   active playbook YAML
```

## Configuration

| Concern | Location |
|---|---|
| Ollama host | `OLLAMA_HOST` env (default `http://127.0.0.1:11434`) |
| Filesystem paths | `synapse/nexus_config.py` |
| Frontend API base URL | `interface/web/src/config.js` |
| Python deps | `requirements-base.txt` + amd/nvidia GPU overlay; `requirements-wsl.txt` = standalone CPU runtime |

---

<div align="center"><sub>NexusOS · local AI, self-hosted on <a href="https://git.enderofwings.com/enderofwings/NexusOS">GitNexus</a></sub></div>