https://github.com/johnforfar/nix-assistant
https://github.com/johnforfar/nix-assistant
Last synced: 13 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/johnforfar/nix-assistant
- Owner: johnforfar
- Created: 2026-04-22T17:59:03.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-22T18:49:06.000Z (about 2 months ago)
- Last Synced: 2026-04-22T20:13:14.456Z (about 2 months ago)
- Language: Python
- Size: 42 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# nix-assistant
An open-source Nix config reviewer for the whole Nix community — paste any flake, NixOS config, home-manager module, or derivation and get structured lint findings + LLM prose advice.
**Live demo:** [nix-assistant.build.openmesh.cloud](https://nix-assistant.build.openmesh.cloud) — running on a sovereign Openmesh Xnode.
**On Hugging Face:**
- Model: [`OpenxAILabs/nix-reviewer-1.5b`](https://huggingface.co/OpenxAILabs/nix-reviewer-1.5b)
- GGUF (Ollama-ready): [`OpenxAILabs/nix-reviewer-1.5b-GGUF`](https://huggingface.co/OpenxAILabs/nix-reviewer-1.5b-GGUF)
- Training data: [`OpenxAILabs/nix-reviewer-training`](https://huggingface.co/datasets/OpenxAILabs/nix-reviewer-training)
## How it works
```
Your Nix config
│
▼
statix + deadnix ──→ deterministic lint findings
│
▼
numpy cosine RAG ──→ top-5 similar nixpkgs/options docs
│
▼
hermes3:3b (Ollama) ──→ prose review with line-level comments
```
- **Corpus**: 98k nixpkgs packages + 16k NixOS options scraped from nixpkgs unstable
- **Embeddings**: nomic-embed-text (768-dim) via Ollama, stored as numpy arrays
- **Model**: hermes3:3b running on shared Ollama instance (no second Ollama)
- **Lint**: statix + deadnix run deterministically before the LLM
- **Backend**: Flask on port 5000, proxied by nginx on port 8080
## Layout
```
nix-assistant/
├── flake.nix # NixOS module — deploys to any xnode via om CLI
├── assistant/
│ ├── server.py # Flask API — POST /api/review, GET /health
│ ├── review.py # full pipeline: lint → retrieve → llm
│ ├── retrieve.py # cosine RAG over numpy embeddings
│ ├── lint.py # statix + deadnix runner
│ └── embed.py # build the numpy vector index from corpus.db
├── scrape/
│ ├── scrape_nixpkgs.py # scrape nixpkgs packages into corpus.db
│ ├── scrape_options.py # scrape NixOS options into corpus.db
│ └── export_hf.py # export corpus.db → parquet shards for HF Hub
└── frontend/
└── index.html # cyberpunk UI (Tron/NixOS blue)
```
## Deploy
```bash
# one-time: add to xnode
om --profile hermes app deploy nix-assistant --flake "github:johnforfar/nix-assistant/v0.1.1"
# push data after first deploy
scp scrape/data/corpus.db :/var/lib/nix-assistant/
scp -r assistant/data/embeddings :/var/lib/nix-assistant/
```
Requires `om` CLI authenticated against an Openmesh Xnode.
The xnode must have a shared `hermes-ollama` container running `hermes3:3b` and `nomic-embed-text`.
## Build embeddings locally
```bash
# scrape (takes ~10 min)
python scrape/scrape_nixpkgs.py
python scrape/scrape_options.py
# embed (requires Ollama with nomic-embed-text, resumable)
python -m assistant.embed --db scrape/data/corpus.db --out assistant/data/embeddings
```
## API
```
POST /api/review
{ "source": "" }
→ { "comments": [{ "line": int, "severity": "error|warning|hint", "message": str }] }
GET /health
→ { "status": "ok", "model": "hermes3:3b" }
```
## Pre-built data
Embedding index (nomic-embed-text 768-dim, ~320MB) is published as a GitHub Release:
**[github.com/johnforfar/nix-assistant/releases/tag/data-v1](https://github.com/johnforfar/nix-assistant/releases/tag/data-v1)**
The NixOS service downloads it automatically on first boot via `ExecStartPre`. You don't need to push anything manually.
## Roadmap
- [ ] Export corpus to HuggingFace Hub (`OpenxAILabs/nix-corpus`)
- [ ] Scrape nixpkgs community flakes for broader coverage
- [ ] Upgrade to qwen2.5-coder:3b for better code understanding
- [ ] PR diff mode — review only changed files