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:
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user