NexusOS/README.md

<div align="center">

<img src="assets/n-small.png" 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 on Linux,
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
# 0. Allow scripts to run (PowerShell blocks unsigned scripts by default, which
#    stops Nexus's CLI from working). Process scope covers only this window;
#    LocalMachine makes it permanent so ncp works from every future shell (run
#    PowerShell as Administrator for the LocalMachine line).
Set-ExecutionPolicy -Scope Process       -ExecutionPolicy Bypass -Force
Set-ExecutionPolicy -Scope LocalMachine  -ExecutionPolicy RemoteSigned -Force

# 1. Install Git, then clone (public repo, no account/token needed):
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
```

Then double-click the **NexusOS** desktop icon, or launch from a **new** shell
(PATH is read at process start, so already-open windows won't have `ncp` yet):

```powershell
ncp web
```

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

### Linux

```bash
# 1. Build everything: venv (auto-selects AMD/NVIDIA/CPU), web UI, memory DB,
#    system packages, Ollama binary and the XFCE desktop wiring.
./install.sh

# 2. Launch (memory :8001, backend :8000 — backend also serves the built UI)
#    The install symlinks ncp into /usr/local/bin (sudo); open a new shell first.
ncp web
```

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

`./install.sh` is also the update path — re-run it any time to pull the latest
and rebuild. `--check` dry-runs it; `--no-desktop` skips the XFCE panel/theme
wiring (that stage is auto-skipped off XFCE anyway). It's a thin wrapper over
`bin/sync.py restore`, the same code the Windows box runs.

### 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
ncp start        # backend + frontend (--backend|--frontend|--memory)
ncp 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
ncp doctor                             # diagnostics: venv, Node, imports, Ollama, status
```

## Architecture

| Component | Location | Role |
|---|---|---|
| **Promethean** (venv) | `Promethean/` | The Python venv all backend code runs in — `source Promethean/bin/activate` (Linux) / `Promethean\Scripts\python.exe` (Windows). Keeps deps out of the system Python. |
| **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
Promethean/       Python venv (gitignored, built by the installer)
```

## 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-windows.txt` = standalone CPU runtime |

## Roadmap

Rough plan, not promises. Ordered by how soon and how much it touches.

### Soon
- **Inference knobs in Settings** — expose temperature, context length, and
  `num_gpu` in the UI. The backend already passes options to Ollama; there's no
  UI for them yet, and small-VRAM boxes need `num_gpu=0` today via env only.
- **Chat controls** — stop generation, regenerate last reply, edit-and-resend.
  History editing exists; live regeneration doesn't.
- **Per-playbook model** — playbooks set the persona but not the model; let a
  playbook pin its own chat model (Settings already splits chat vs. memory model).

### Eventually
- **Document ingest / RAG** — the embedding stack (nomic-embed-text,
  `message_vectors`, cosine recall) already retrieves past conversations. Extend
  it to uploaded files and notes so chats can cite your own documents.
- **Vision chat** — attach images to a message and route to a multimodal Ollama
  model. The stream path is text-only today.
- **Real vector index** — recall does a brute-force cosine scan over JSON blobs
  in SQLite. Fine at current scale; swap in a proper index (e.g. sqlite-vec)
  before the DB grows.

### Far future
- **macOS support** — POSIX process control already works; needs a `sync.py`
  platform fork, ROCm-free requirements, and an installer. Waiting on a Mac.
- **Voice I/O** — local speech-to-text in, text-to-speech out.
- **Fine-tuning loop** — conversations already export as ShareGPT; close the
  loop into a local fine-tune. The ML stack was stripped from the runtime venv
  but the requirements files restore it.
- **Tool-using playbooks** — function calling so a playbook can take actions,
  not just shape the prompt.
- **Machine learning & gameplay** — the original goal: an agent that learns to
  play games alongside me (it started as "teach it to play Lego Star Wars").
  Screen capture in, controller/input out, trained by playing. The whole reason
  this project exists.

---

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