{"id":50495351,"url":"https://github.com/johnforfar/nix-assistant","last_synced_at":"2026-06-02T06:30:32.036Z","repository":{"id":353172316,"uuid":"1218276711","full_name":"johnforfar/nix-assistant","owner":"johnforfar","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-22T18:49:06.000Z","size":43,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-22T20:13:14.456Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/johnforfar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-22T17:59:03.000Z","updated_at":"2026-04-22T18:49:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/johnforfar/nix-assistant","commit_stats":null,"previous_names":["johnforfar/nix-assistant"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/johnforfar/nix-assistant","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnforfar%2Fnix-assistant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnforfar%2Fnix-assistant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnforfar%2Fnix-assistant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnforfar%2Fnix-assistant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/johnforfar","download_url":"https://codeload.github.com/johnforfar/nix-assistant/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnforfar%2Fnix-assistant/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33810341,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-02T06:30:30.956Z","updated_at":"2026-06-02T06:30:32.030Z","avatar_url":"https://github.com/johnforfar.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nix-assistant\n\nAn 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.\n\n**Live demo:** [nix-assistant.build.openmesh.cloud](https://nix-assistant.build.openmesh.cloud) — running on a sovereign Openmesh Xnode.\n\n**On Hugging Face:**\n- Model: [`OpenxAILabs/nix-reviewer-1.5b`](https://huggingface.co/OpenxAILabs/nix-reviewer-1.5b)\n- GGUF (Ollama-ready): [`OpenxAILabs/nix-reviewer-1.5b-GGUF`](https://huggingface.co/OpenxAILabs/nix-reviewer-1.5b-GGUF)\n- Training data: [`OpenxAILabs/nix-reviewer-training`](https://huggingface.co/datasets/OpenxAILabs/nix-reviewer-training)\n\n## How it works\n\n```\nYour Nix config\n      │\n      ▼\nstatix + deadnix ──→ deterministic lint findings\n      │\n      ▼\nnumpy cosine RAG ──→ top-5 similar nixpkgs/options docs\n      │\n      ▼\nhermes3:3b (Ollama) ──→ prose review with line-level comments\n```\n\n- **Corpus**: 98k nixpkgs packages + 16k NixOS options scraped from nixpkgs unstable\n- **Embeddings**: nomic-embed-text (768-dim) via Ollama, stored as numpy arrays\n- **Model**: hermes3:3b running on shared Ollama instance (no second Ollama)\n- **Lint**: statix + deadnix run deterministically before the LLM\n- **Backend**: Flask on port 5000, proxied by nginx on port 8080\n\n## Layout\n\n```\nnix-assistant/\n├── flake.nix             # NixOS module — deploys to any xnode via om CLI\n├── assistant/\n│   ├── server.py         # Flask API — POST /api/review, GET /health\n│   ├── review.py         # full pipeline: lint → retrieve → llm\n│   ├── retrieve.py       # cosine RAG over numpy embeddings\n│   ├── lint.py           # statix + deadnix runner\n│   └── embed.py          # build the numpy vector index from corpus.db\n├── scrape/\n│   ├── scrape_nixpkgs.py # scrape nixpkgs packages into corpus.db\n│   ├── scrape_options.py # scrape NixOS options into corpus.db\n│   └── export_hf.py      # export corpus.db → parquet shards for HF Hub\n└── frontend/\n    └── index.html        # cyberpunk UI (Tron/NixOS blue)\n```\n\n## Deploy\n\n```bash\n# one-time: add to xnode\nom --profile hermes app deploy nix-assistant --flake \"github:johnforfar/nix-assistant/v0.1.1\"\n\n# push data after first deploy\nscp scrape/data/corpus.db       \u003cxnode\u003e:/var/lib/nix-assistant/\nscp -r assistant/data/embeddings \u003cxnode\u003e:/var/lib/nix-assistant/\n```\n\nRequires `om` CLI authenticated against an Openmesh Xnode.\nThe xnode must have a shared `hermes-ollama` container running `hermes3:3b` and `nomic-embed-text`.\n\n## Build embeddings locally\n\n```bash\n# scrape (takes ~10 min)\npython scrape/scrape_nixpkgs.py\npython scrape/scrape_options.py\n\n# embed (requires Ollama with nomic-embed-text, resumable)\npython -m assistant.embed --db scrape/data/corpus.db --out assistant/data/embeddings\n```\n\n## API\n\n```\nPOST /api/review\n  { \"source\": \"\u003cnix config string\u003e\" }\n  → { \"comments\": [{ \"line\": int, \"severity\": \"error|warning|hint\", \"message\": str }] }\n\nGET /health\n  → { \"status\": \"ok\", \"model\": \"hermes3:3b\" }\n```\n\n## Pre-built data\n\nEmbedding index (nomic-embed-text 768-dim, ~320MB) is published as a GitHub Release:\n\n**[github.com/johnforfar/nix-assistant/releases/tag/data-v1](https://github.com/johnforfar/nix-assistant/releases/tag/data-v1)**\n\nThe NixOS service downloads it automatically on first boot via `ExecStartPre`. You don't need to push anything manually.\n\n## Roadmap\n\n- [ ] Export corpus to HuggingFace Hub (`OpenxAILabs/nix-corpus`)\n- [ ] Scrape nixpkgs community flakes for broader coverage\n- [ ] Upgrade to qwen2.5-coder:3b for better code understanding\n- [ ] PR diff mode — review only changed files\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnforfar%2Fnix-assistant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohnforfar%2Fnix-assistant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnforfar%2Fnix-assistant/lists"}