docs(readme): add Modules section, bulletpoint dense prose

New Modules entry in Flagship features + Architecture describes the
modules/ plugin auto-discovery. Chat/vision/voice, action tools,
Layout, and Configuration reworded from prose/tables into bullets for
scannability.
This commit is contained in:
Jon Wingender
2026-08-05 18:53:54 -05:00
parent 5d997886e6
commit 0508249eb9
+39 -25
View File
@@ -29,11 +29,13 @@ tail of the service logs.
## Flagship features
### Chat, vision & voice
Streaming responses over SSE, with stop/regenerate/edit-and-resend so a bad
reply doesn't mean retyping the whole message. Attach images and route them to
a multimodal Ollama model for vision. Dictate with local Whisper STT instead
of typing, and have replies read back aloud. A per-message extended-thinking
toggle lets a reasoning model show its work without a round-trip to Settings.
- **Streaming replies** over SSE, with stop/regenerate/edit-and-resend so a
bad reply doesn't mean retyping the whole message
- **Vision** — attach images and route them to a multimodal Ollama model
- **Voice** — dictate with local Whisper STT instead of typing, and have
replies read back aloud
- **Extended thinking** — a per-message toggle lets a reasoning model show
its work without a round-trip to Settings
### Persistent memory
A dedicated microservice reads every exchange and decides, via its own Ollama
@@ -56,17 +58,30 @@ sqlite-vec index and cites the matching passages back into chat answers.
draws on that project's documents (or none, in the unscoped "All" view).
### Action tools with an approval gate
Beyond read-only tools (search memory/history/documents, list models, get the
time), Nexus can search the web, fetch a URL, or save a fact on its own
initiative — but each of those three is gated behind an explicit approval
prompt in the chat UI before it runs. Nothing reaches out to the network or
writes to memory without you seeing the request first.
- **Read-only, run automatically** — search memory/history/documents, list
models, get the time
- **Gated, need approval** — search the web, fetch a URL, save a fact.
Each one prompts in the chat UI before it runs, so nothing reaches out to
the network or writes to memory without you seeing the request first
### Model management
List, pull, and delete Ollama models from the UI or `ncp`, with hardware-aware
recommendations (GPU detection via Vulkan) so a small-VRAM box isn't offered a
model it can't run.
### Modules
Feature areas beyond the core assistant live as self-contained plugins
instead of being wired into the core app:
- **Mail** — IMAP/SMTP, multiple accounts
- **Network** — connection status, WireGuard toggle, ping targets
A backend module is a folder under `modules/` with a `router.py`; a frontend
module is a folder under `interface/web/src/modules/` with a `module.jsx`
exporting a manifest and a component. Both sides are auto-discovered at
startup/build — dropping in a new module folder is enough to have it mounted
and show up in the UI, no registry file to edit.
## Quick start
NexusOS runs **single-process**: the backend on `:8000` serves the built web UI
@@ -196,6 +211,7 @@ ncp help # see complete help tree
| **Documents / RAG** | `synapse/memory/store.py` | PDF/DOCX/TXT/MD ingest, chunked and embedded, retrieved via a sqlite-vec index; scoped per **Project** workspace. |
| **Action tools** | `synapse/tools.py`, `synapse/search.py` | Read-only tools (search memory/history/documents, list models, get time) run automatically; `web_search`, `fetch_url`, and `remember` require per-call approval from the chat UI. |
| **Playbooks** | `synapse/playbooks/` + `data/playbooks/` | Ordered `{id}.yaml` records managed by `PlaybookManager`; each can pin a chat model and a tool list. |
| **Modules** | `modules/` + `interface/web/src/modules/` | Self-contained feature plugins (Mail, Network). Backend: any `modules/*/router.py` is auto-mounted. Frontend: any `interface/web/src/modules/*/module.jsx` is auto-registered in the UI. No registry file to edit. |
| **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, Models, Memory, Documents, Logs, Settings. |
@@ -208,24 +224,22 @@ are the exception (YAML files in `data/playbooks/`). All paths are defined in
## 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)
```
- `synapse/` — FastAPI backend + memory service + playbook/ollama managers
- `modules/` — auto-discovered feature plugins
- `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 |
- **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
## Issues and feature requests