Skip to content
Discod73Public

About

Local-first, privacy-preserving multi-agent AI system for families. Runs on Raspberry Pi 5 + Jetson Orin NX. No cloud. No subscriptions. Your data stays home.

Resources

Code of conduct

Contributing

Stars

10 stars

Watchers

0 watching

Forks

Repository files navigation

NOUS — Locally-hosted Personal AI Assistant

NOUS is a privacy-first, locally-hosted personal AI system. All data stays on your own hardware — nothing leaves your network unless you explicitly choose to use an external AI provider via the built-in external API feature.

What it does

  • RAG over your documents — ingest PDFs, Word files and text, query them in natural language
  • Voice interface — wake-word detection → Whisper STT → local LLM → Piper TTS
  • Web cockpit — browser UI with wings (topic-based document collections), analysis mode, and scraper jobs
  • Scope system — documents tagged SECRET / PRIVATE / SWARM / PUBLIC with enforced access controls
  • Optional external AI — send queries to Anthropic, OpenAI, Groq or a custom endpoint; key stays in browser session only
  • Multi-user — admin user plus family profiles with configurable wing access
  • Compute lending — swarm nodes can delegate inference to idle peers during off-hours; SECRET/PRIVATE scope is hardcoded never to leave the originating node; credit system tracks contribution on both sides; automatic local fallback on peer failure
  • GBrain — graph inference over the Kuzu knowledge base; identifies alienation patterns and source-concentration across extracted facts
  • Swarm shadow observer — read-only telemetry agent verified over 24 h with zero boundary violations; monitors health, Qdrant, and isolation gates every minute

Hardware

The system is designed for a two-device LAN setup, but can run on a single machine:

Device Role Tested on
Primary host (Pi 5 recommended) API, RAG, ingest, web UI, proxy Raspberry Pi 5 16GB
Inference host LLM + STT Jetson Orin NX 16GB
Swarm + compute node Peer inference, knowledge sharing Jetson Orin NX 8GB (permanent swarm node)

Single-machine: point NOUS_OLLAMA_URL and NOUS_WHISPER_URL at localhost.

Multi-agent architecture

NOUS uses specialised agents for different domains (household, legal, legacy). Each agent is designed to run its own model, but on constrained hardware models are shared intelligently:

  • Daily use (supervisor, household, children): qwen2.5:7b — kept permanently in memory for instant response
  • Night analysis (legal, inconsistency): qwen3:14b — loads on-demand

When hardware with larger unified memory (32GB+) becomes available, or domain-specific models are released as GGUF, each agent can be configured with its own specialised model without architectural changes.

Quick start

1. Infrastructure (Docker)

cd /srv/nous
docker compose up -d        # starts Qdrant + SearXNG

2. Python environment

python3 -m venv pipeline/.venv
source pipeline/.venv/bin/activate
pip install -r pipeline/requirements.txt   # fastapi uvicorn httpx qdrant-client ...

3. Configuration

cp .env.example .env
# Edit .env — set NOUS_OWNER_NAME and network addresses

cp config/wings.example.json config/wings.json
# Edit wings.json — define your document collections

4. Start the API

cd /srv/nous/api
uvicorn main:app --host 0.0.0.0 --port 8000

Open web/index.html in a browser (or serve it via nginx — see docs/CREDITS.md).

5. Systemd service (optional)

sudo cp api/nous-api.service /etc/systemd/system/
sudo systemctl enable --now nous-api.service

Wings and scopes

Wings are named document collections. Each wing has a scope:

Scope Who can see it PII anonymization on export
SECRET Admin only None
PRIVATE Admin only None
SWARM All users All PII masked
PUBLIC Everyone CPR, phone, address, email masked

Non-admin users can be blocked from specific wings via blockedWings in web/index.html → USERS.

Drop files into incoming/<wing-name>/ for automatic ingest (picked up within ~10 seconds by the file watcher).

Voice setup

Requires: any USB microphone, Piper TTS model, Whisper running on inference host.

Optional hardware: ReSpeaker/XVF3800 users may install their vendor control tools separately — NOUS auto-detects the device by name. See your hardware vendor's documentation.

# Download Danish Piper TTS model
mkdir -p models/tts
# Place da.onnx and da.onnx.json in models/tts/

# Test voice pipeline
bash scripts/voice_test.sh

See CLAUDE.md for full architecture details.

External AI

The web cockpit includes an optional external AI panel (🌐) in Analyse and Assistant modes. When enabled, queries are sent to Anthropic / OpenAI / Groq / custom endpoint after scope confirmation. The API key is never stored — it lives only in the browser session.

PRIVATE wings require one confirmation click. SECRET wings require typing a confirmation phrase (configurable in web/index.html) before sending.

Project structure

api/          FastAPI backend
config/       wings.json, scraper_jobs.json (gitignored — use *.example.json)
docs/         Architecture notes, credits
models/       TTS + embedding models (gitignored)
pipeline/     Ingest pipeline, privacy guard, task router
proxy/        Lightweight internet proxy for LAN-isolated inference host
scripts/      CLI tools: voice_chat.py, nous_chat.py, promote.py, ...
web/          Single-file cockpit UI (index.html)

Changelog

v0.2.0

  • Compute lending: swarm peers can serve delegated inference with scope-guard and credit tracking
  • GBrain: graph inference over Kuzu DB for pattern detection across facts
  • Swarm shadow observer: 24 h read-only telemetry verification with zero boundary violations
  • Jetson Orin NX 8GB added as permanent swarm + compute node

v0.1.0

  • Initial release: RAG, voice, cockpit UI, scope system, swarm knowledge sharing, night pipeline

License

AGPL-3.0 — see LICENSE.

About

Local-first, privacy-preserving multi-agent AI system for families. Runs on Raspberry Pi 5 + Jetson Orin NX. No cloud. No subscriptions. Your data stays home.

Resources

Code of conduct

Contributing

Stars

10 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages