[Skill] RAG de recherche dans la documentation locale avec installation assistée pour Openfox / Fully asssited RAG skill installation for Openfox (the best)

[cried-nutty-won]

---

[skill] now integrated into openfox

For minimal context usage:

Use Project instructions instead of the skill for local LLMs below 70B.

Use the skill only with large models on high-spec hardware or cloud-based LLMs.

The skill can be activated or disabled.

RAG works without the skill outside OpenFox.

Prelaunch RAG manually with 'llmes' for CPU users or 'llmers' for GPU users.

Check status with 'rc' and vault indexation completion with 'rst'.

Use 'rag all "query" on CPU or 'ragr all "query" on GPU for your query.

The OpenFox agent can use RAG through Project instructions.

[Project Instructions] Right of new session, Edit Project settings, add

Before launching the first command and before answering ANY question about my environment, configuration, notes, docs, passwords, procedures or security policies, you MUST first run:

  rag all "<query>"

Use the returned passages. Cite `source` and `path`. If rag returns an error or nothing, tell me and stop. Never debug, restart, or modify rag. Never ask permission to search.
If rag is unreachable, run `llme` to restart the embedding service, `rc` to check status, `rst` to check vault scan completion, then retry once.

for gpu owners only, add :

Use `rag all "<query>"` for quick lookups, `ragr all "<query>"` for thorough/precise searches.

---

Salut Conrad,

Je propose un skill RAG qui permet à l'agent OpenFox
avec un mini llm spécialisé en recherche documentaire de 0,6B
et un second mini llm de 0,6B spécialisé en classement de chercher efficacement
dans la documentation locale, coffres Obsidian, docs techniques, manuels, procédures...
et ainsi gagner en tokens, en vitesse, en écomomie d'énergie, en qualité et en précision.

Pas de MCP, pas de plugin, pas de process supplémentaire.
Un fichier .md dans le dossier de skills + le terminal intégré.
L'agent contrôle tout lui-même via 10 raccourcis shell.

Après une version en plugins puis en MCP j'ai finalement tout jeter pour la version skills.
Solution nettement supérieure étant donné qu'elle ne surcharge pas trop le contexte de l'agent au départ.
Pour les llm locaux inférieurs à 70B, il faut laisser la skill désactivée et ajouter les Project instructions ci-dessus.
L'installation est 100% assistée, rien à faire!
juste se laisser guider.

Repos :

• Skill + installateur : https://github.com/cried-nutty-won/openfox-rag
• Serveur RAG (Python) : https://github.com/cried-nutty-won/rag-system

Le problème

Quand l'agent travaille sur un projet, il n'a aucun moyen de consulter la
documentation locale de l'utilisateur. Il doit soit halluciner, soit demander
à l'utilisateur de coller la doc manuellement dans le contexte.

S'il a accès aux fichiers, il va surcharger son contexte inutilement.
Le rag permet une dissection chirurgicale prémâchée de la doc qui lui permettra d'extraire
uniquement les informations pertinentes en perdant le minimum de tokens
et donc en accélérant drastiquement les recherches.

Concrètement, si j'ai une procédure nftables dans mes notes Obsidian et que
je demande à l'agent de configurer un firewall, il ne peut pas la trouver.
Il va générer une config générique, probablement incorrecte pour mon setup.
etc...

La solution : un skill + le terminal intégré

Un fichier skill (.md) dans le dossier de skills d'OpenFox instruit l'agent
d'utiliser le terminal intégré pour contrôler la stack RAG :

rc                          # Les services sont-ils actifs ?
llmers                      # Démarre la stack complète
ragr void "nftables"        # Recherche précise (avec reranker)
rag void "nftables"         # Recherche rapide (RRF seul)
rst                         # Tail des logs
rsk                         # Arrête le serveur

Exactement comme l'agent utilise déjà le terminal pour git status,
npm install, ou n'importe quelle commande shell.

Le serveur RAG est un service indépendant (repo séparé).
L'agent n'a besoin que d'un fichier .md pour savoir comment l'appeler.

Pourquoi pas un plugin

J'ai lu la doc des plugins OpenFox. L'API ProviderPluginRegistry ne supporte
que les providers :

registry.registerAuth(auth)
registry.registerTransport(transport)
registry.registerPreset(preset)

Il n'y a pas de registry.registerTool(). Les tools sont dans le core
(src/server/tools/), pas dans les plugins. Un plugin ne peut pas ajouter
un tool rag_search.

Pourquoi pas un MCP

Un MCP serait fonctionnel (exactement le pattern de Brave Search), mais c'est
un process Node.js supplémentaire avec le protocole JSON-RPC over stdio,
des dépendances npm, et une configuration JSON dans Settings > Tools > MCP.

Pour ce que c'est — appeler un endpoint HTTP et lire du JSON — le terminal
intégré fait exactement la même chose avec zéro dépendance. L'agent sait
déjà utiliser curl. Un fichier .md lui dit quand et comment.

Les 10 raccourcis

Commande	Action
llmers	Démarrer la stack complète (embedding + reranker + RAG)
llmes	Démarrer embedding + RAG (sans reranker)
llme	Démarrer l'embedding seul (port 8181)
llmr	Démarrer le reranker seul (port 8184)
rs	Démarrer le serveur RAG seul (port 8182)
rst	Tail -f des logs RAG
rag <vault> "<requête>"	Recherche rapide (~20ms)
ragr <vault> "<requête>"	Recherche lente et précise avec reranker (~10-18s CPU, ~1s GPU)
rc	Health check des 3 services
rsk	Tuer le serveur RAG

L'agent contrôle l'intégralité de la stack de manière autonome.
Il vérifie la santé, démarre, recherche, surveille et arrête — tout seul.

Le pipeline de recherche

Requête utilisateur
       │
       ├──→ Embedding (Qwen3-0.6B ou 4B) → Cosine similarity → Ranking vectoriel
       │                                                              │
       └──→ Tokenisation → BM25Okapi → Ranking BM25                  │
                                        │                             │
                                        └── RRF (k=60) ──────────────┘
                                                 │
                                         Top 18 candidats
                                                 │
                                         Reranker (Qwen3-0.6B ou 4B)
                                         (cross-encoder, lit query+doc conjointement)
                                                 │
                                         Résultats finaux

Le reranker est l'étape qui apporte le plus de gain qualitatif.
Dans le benchmark FinanceQA de Dave Ebbelaar ("Hybrid Retrieval from Scratch", 2026),
l'ajout d'un reranker améliore le NDCG@10 de +12 points.

Installation

Un seul script interactif :

mkdir -p ~/rag
git clone https://github.com/cried-nutty-won/openfox-rag.git ~/rag/openfox-rag
cd ~/rag/openfox-rag
bash install.sh

L'installateur :

• Détecte l'OS, la RAM, le GPU (NVIDIA, Apple Silicon, lspci)
• Détecte le shell (fish, bash, zsh, sh) et écrit les alias dans le bon fichier
• Propose les modèles 0.6B (défaut) ou 4B (GPU uniquement — masqués sur CPU)
• Télécharge les GGUF depuis Qwen officiel + Voodisss
• Clone et configure rag-system
• Scanne les vaults Obsidian et documentation (boucle interactive)
• Installe le skill OpenFox (~/.config/openfox/skills/rag-search.md)
• Affiche toutes les commandes et les chemins vers la doc à la fin

Mode dry-run pour tester sans rien modifier : bash install.sh --dry-run

Désinstaller

cd ~/rag/openfox-rag
bash uninstall.sh

---

Compatibilité backend

Backend	Embedding	Reranking	Mode RAG
llamacpp	✅ POST /embedding	✅ POST /v1/rerank	Hybride + Reranker
vLLM	✅ POST /v1/embeddings	✅ POST /v1/rerank	Hybride + Reranker
sglang	✅ POST /v1/embeddings	✅ POST /v1/rerank	Hybride + Reranker
ollama	✅ POST /api/embeddings	❌	Hybride (RRF uniquement)

Le serveur RAG s'adapte automatiquement : si le reranker est injoignable,
il bascule en RRF pur sans erreur.

Avec ton cluster DGX Spark (vLLM), le RAG bénéficie du batching natif
et des sessions concurrentes. Les modèles embedding et reranker peuvent
être servis par le même backend que le LLM de chat.

Intégration dans les workflows

Avec les workflows custom (système de blocs), on peut ajouter une étape
"research" avant "build" :

[Research (RAG)] → [Build] → [Verify] → [Code Review] → [Summary]

Et dans les General Instructions :

Avant de coder, consulte toujours la base de connaissances locale
via le terminal. Exécute : rc
Puis : ragr obsidian "ta requête"
Utilise les passages retournés comme contexte. Cite toujours le fichier source.

Points techniques critiques

GGUF reranker : Voodisss uniquement

Les GGUF communautaires de Qwen3-Reranker sont cassés (llama.cpp #16407).
Il leur manque le tenseur cls.output.weight (classifieur yes/no),
le metadata pooling_type=RANK et le chat template de reranking.
Résultat : scores poubelles (4.5e-23).

Seuls les GGUF de Voodisss (convertis avec le convert_hf_to_gguf.py officiel)
fonctionnent.

Pooling

• Embedding : pooling = last (hidden state du token [EOS] final).
  Le blog officiel Qwen3 dit explicitement last.
• Reranker : pooling = rank (obligatoire, active le classifieur).

Host prompt cache

llama.cpp PR #16391 active par défaut un cache prompt de 8 GiB en RAM host.
Pour un serveur embedding/reranker où les prompts ne sont jamais réutilisés,
ajouter --cache-ram 0 pour éviter l'OOM.

Performance

Métrique	Recherche rapide	Recherche précise (0.6B)	Recherche précise (4B)
Latence (CPU)	~20 ms	~10-18 s	~30-40 s (trop lent)
Latence (GPU)	~3 ms	~1 s	~3 s
RAM / VRAM	~1.7 Go	~1.7 Go	~6 Go
Précision (NDCG@10)	baseline	+12 pts	+16 pts

Ce que je propose de faire

1. Le skill et l'installateur sont déjà prêts :
   https://github.com/cried-nutty-won/openfox-rag
2. Le serveur RAG est fonctionnel et documenté :
   https://github.com/cried-nutty-won/rag-system
3. Si tu veux, je peux ouvrir une PR pour ajouter le skill dans la doc
   d'OpenFox ou dans les General Instructions par défaut

Références

• openfox-rag — skill + installateur
• rag-system — serveur RAG (Python)
• Qwen3 Embedding — doc officielle
• Voodisss GGUF — GGUF reranker fonctionnels
• Guide Voodisss multi-modèles — models.ini
• llama.cpp #16407 — GGUF reranker cassés
• Dave Ebbelaar, "Hybrid Retrieval from Scratch" (2026) — méthodologie

Si ça t'intéresse, dis le moi, test de ton côté, les install et uninstall sont fonctionnels chez moi, à voir chez toi ou chez d'autres si c'est bien fonctionnel. Dites-moi si vous voyez des choses à améliorer. Et si ça te plaìt à toi de voir comment l'intégrer dans le détail.
En tous cas merci pour le merveilleux Openfox et pour tes videos.

Eric

[cried-nutty-won]

openfox-rag

RAG integration for OpenFox. A skill file that teaches the OpenFox agent to search local knowledge bases (Obsidian vaults, technical docs, procedures) through a hybrid retrieval pipeline: BM25 + Vector → RRF → Cross-encoder Reranker.

No MCP, no plugin, no additional process. The RAG server runs independently (rag-system), and the agent controls it entirely via its built-in terminal using 10 shell shortcuts.

Why

Without RAG	With openfox-rag
Agent hallucinates or asks user to paste docs	Agent searches the knowledge base autonomously
Entire corpus stuffed into context (thousands of tokens)	5-10 relevant chunks (~2000 tokens)
Maximum compute per query	Compute proportional to actual relevance
Often depends on cloud APIs	100% local, no data leaves the machine

How it works

OpenFox Agent
    │
    ├──→ Built-in terminal
    │         │
    │         ├──→ rc          (health check)
    │         ├──→ llmers      (start full stack)
    │         ├──→ ragr void "query"   (precise search)
    │         ├──→ rag void "query"    (fast search)
    │         ├──→ rst         (tail logs)
    │         └──→ rsk         (stop server)
    │
    └──→ Skill file (skills/rag-search.md)
              └──→ Tells the agent when and how to use each command

Zero additional processes on the OpenFox side. The RAG server is a separate, independent service. The agent starts it, searches it, monitors it, and stops it — all from the terminal, exactly like any other command-line tool.

---

Installation

git clone https://github.com/cried-nutty-won/openfox-rag.git
cd openfox-rag
bash install.sh

The installer:

• Detects OS, RAM, GPU (NVIDIA, Apple Silicon, lspci)
• Detects shell (fish, bash, zsh, sh) and writes aliases to the correct config
• Offers 0.6B models (default) or 4B models (GPU only — hidden on CPU)
• Downloads GGUF from official Qwen + Voodisss
• Clones and configures rag-system
• Scans for Obsidian and documentation vaults (interactive loop)
• Installs the OpenFox skill (~/.config/openfox/skills/rag-search.md)
• Displays all commands and documentation paths at the end

Dry-run mode

Test without modifying anything:

bash install.sh --dry-run

Commands

Command	Action
llmers	Start full stack (embedding + reranker + RAG server)
llmes	Start embedding + RAG server (no reranker)
llme	Start embedding only (port 8181)
llmr	Start reranker only (port 8184)
rs	Start Python RAG server only (port 8182)
rst	Tail -f RAG server logs
rag <vault> "<query>"	Fast search (~20ms)
ragr <vault> "<query>"	Slow and precise search with reranker (~10-18s CPU, ~1s GPU)
rc	Health check all 3 services
rsk	Kill the Python RAG server

Vaults

Configured interactively during installation. Each vault has a short name used in commands:

rag void "nftables configuration"        # search vault "void"
ragr linux "dracut hooks"                 # precise search in "linux"
ragr all "your query"                     # search all vaults
rag obsidian "your query"                 # search all Obsidian vaults

---

Model selection

Hardware	Embedding	Reranker	Why
CPU only (8 GB RAM)	0.6B Q8_0	0.6B Q4_K_M	Fits in RAM, interactive latency
GPU (6+ GB VRAM)	4B Q4_K_M	4B Q4_K_M	Best quality, ~3s for 100 candidates
GPU (24+ GB VRAM)	4B F16	4B F16	Maximum quality, no quantization loss

GGUF models

Model	Quant	Size	Hardware	MTEB
Qwen3-Embedding-0.6B	Q8_0	610 MB	CPU or GPU	64.33
Qwen3-Embedding-4B	Q4_K_M	2.4 GB	GPU recommended	69.45
Qwen3-Reranker-0.6B	Q4_K_M	379 MB	CPU or GPU	65.80
Qwen3-Reranker-4B	Q4_K_M	2.4 GB	GPU recommended	69.76

• Embedding: Qwen/Qwen3-Embedding-0.6B-GGUF or Qwen/Qwen3-Embedding-4B-GGUF (official)
• Reranker: Voodisss/Qwen3-Reranker-0.6B-GGUF-llama_cpp or Voodisss/Qwen3-Reranker-4B-GGUF-llama_cpp (mandatory — community GGUFs are broken, see llama.cpp #16407)

---

MTEB (Massive Text Embedding Benchmark) is the reference benchmark for evaluating embedding model quality. It measures a model's ability to produce vectors that capture text meaning, across 8 task types:

Task	What it measures	Example
Retrieval	Finding the right document among thousands	"What is the nftables procedure?" → find the right file
Reranking	Reordering candidates by relevance	Rank 18 chunks from most to least relevant
Classification	Categorizing a text	"Is this document about networking or storage?"
Clustering	Grouping similar texts	Group notes by topic
STS (Semantic Textual Similarity)	Measuring similarity between two sentences	"nftables firewall" ≈ "nftables firewall rules"
Pair Classification	Determining if two texts are related	"Does this procedure match this question?"
Bitext Mining	Finding the corresponding translation	FR ↔ EN
Summarization	Evaluating summary quality	—

Why it matters for RAG

The MTEB Retrieval score is the most important for RAG: it directly measures the model's ability to find the right document. The higher the score, the less the RAG needs the reranker to compensate.

Model	MTEB Multilingual	MTEB Retrieval	Dimensions
Qwen3-Embedding-0.6B	64.33	64.64	1024
Qwen3-Embedding-4B	69.45	69.60	2560
Qwen3-Embedding-8B	70.58	70.88	4096

The 0.6B is sufficient for a local RAG with reranker. The 4B adds +5 points but requires a GPU.

---

Backend Configuration

The embedding and reranker models can be served by the same backend as the chat LLM, or by separate llama-server instances. See presets/models-llamacpp.ini for a ready-to-use configuration.

llamacpp (models.ini)

One server, one port, three models. The router swaps models in/out of VRAM on demand.

0.6B models (CPU-friendly, ~1 GB total)

[*]
n-gpu-layers = all
batch-size = 2048
ubatch-size = 2048
load-on-startup = Qwen3-Embedding-0.6B

[Qwen3-Embedding-0.6B]
model = /path/to/Qwen3-Embedding-0.6B-Q8_0.gguf
embedding = true
pooling = last
ctx-size = 8192

[Qwen3-Reranker-0.6B]
model = /path/to/Qwen3-Reranker-0.6B-Q4_K_M.gguf
reranking = true
pooling = rank
embedding = true
ctx-size = 1024

[deepseek-v4-flash]
model = /path/to/DeepSeek-V4-Flash.gguf
ctx-size = 32768

4B models (GPU recommended, ~5 GB total)

[*]
n-gpu-layers = all
batch-size = 2048
ubatch-size = 2048
load-on-startup = Qwen3-Embedding-4B

[Qwen3-Embedding-4B]
model = /path/to/Qwen3-Embedding-4B-Q4_K_M.gguf
embedding = true
pooling = last
ctx-size = 32768

[Qwen3-Reranker-4B]
model = /path/to/Qwen3-Reranker-4B-Q4_K_M.gguf
reranking = true
pooling = rank
embedding = true
ctx-size = 32768

[deepseek-v4-flash]
model = /path/to/DeepSeek-V4-Flash.gguf
ctx-size = 32768

llama-server --host 127.0.0.1 --port 8000 --models-max 1 --models-preset models.ini

Note on pooling: The official Qwen3 blog says last (hidden state of the final [EOS] token) for embedding. Some community guides say mean. Official docs take precedence: use last.

vLLM (GPU cluster)

vllm serve Qwen/Qwen3-Embedding-0.6B \
  --served-model-name Qwen3-Embedding-0.6B \
  --task embedding --port 8000 &

vllm serve Qwen/Qwen3-Reranker-0.6B \
  --served-model-name Qwen3-Reranker-0.6B \
  --task score --port 8001 &

sglang

python -m sglang.launch_server \
  --model-path Qwen/Qwen3-Embedding-0.6B \
  --is-embedding --port 8000 &

ollama (embedding only)

Ollama does not support reranking. The RAG server automatically falls back to pure RRF (BM25 + vector, no reranker).

ollama pull qwen3-embedding:0.6b

# RAG server configuration for ollama
export LLAMA_EMBED_URL="http://127.0.0.1:11434/api/embeddings"
# No reranker URL — automatic RRF fallback

Backend compatibility summary

Backend	Embedding	Reranking	RAG mode
llamacpp	✅ POST /embedding	✅ POST /v1/rerank	Hybrid + Reranker
vLLM	✅ POST /v1/embeddings	✅ POST /v1/rerank	Hybrid + Reranker
sglang	✅ POST /v1/embeddings	✅ POST /v1/rerank	Hybrid + Reranker
ollama	✅ POST /api/embeddings	❌	Hybrid (RRF only)

The RAG server adapts automatically: if the reranker is unreachable, it falls back to pure RRF without error.

Workflow Integration

Custom workflow step

Add a "Research" step before "Build" in OpenFox's workflow editor:

[Research (RAG)] → [Build] → [Verify] → [Code Review] → [Summary]

General Instructions

Add to your OpenFox General Instructions:

Before coding, always consult the local knowledge base via the terminal.
Run: rc
Then: ragr obsidian "your query"
Use the retrieved passages as context. Always cite the source file.

Performance

Metric	Fast search	Precise search (0.6B)	Precise search (4B)
Latency (CPU)	~20 ms	~10-18 s (18 candidates)	~30-40 s (too slow)
Latency (GPU)	~3 ms	~1 s (100 candidates)	~3 s (100 candidates)
RAM / VRAM	~1.7 GB	~1.7 GB	~6 GB
Accuracy (NDCG@10)	baseline	+12 pts	+16 pts

Known Limitations

• Reranker GGUF: Only Voodisss GGUFs work. Community conversions are broken (missing cls.output.weight tensor). See llama.cpp #16407.
• Host prompt cache: llama.cpp PR #16391 defaults to 8 GiB host prompt cache. For embedding/reranker servers where prompts are never reused, add --cache-ram 0 to prevent OOM.
• Reranker candidates > 21 on CPU: The reranker crashes. 18 is the stable sweet spot.
• No hot-reload: Modifying an Obsidian file requires cache clear + re-index.
• Orphan cache: Deleted chunks remain in the JSON cache (no garbage collection yet).
• Agent must parse output: The agent reads the command output and extracts relevant passages. Works well with models ≥ 7B.

References

• OpenFox — local-LLM-first agentic coding assistant
• rag-system — standalone RAG server (Python)
• Qwen3 Embedding blog — official documentation
• Voodisss multi-model guide — llamacpp models.ini reference
• Voodisss Reranker GGUF — working GGUF conversions
• llama.cpp #16407 — why community reranker GGUFs are broken
• llama.cpp PR #16391 — host prompt cache (8 GiB default)
• Dave Ebbelaar, "Hybrid Retrieval from Scratch" (2026) — methodology

License

MIT — consistent with the OpenFox ecosystem.

[cried-nutty-won]

c'est bleuffant en tout cas, ça accélère vraiment le llm de base. Gain de temps, gain de tokens, gain en précision, gain en consommation d'énergie. Et on peut l'utiliser aussi soi-même en dehors du harnais d'agents en usage perso. bravo en tous cas pour ton merveilleux openfox, pour tes videos et ton talent.
le rag fonctionne à merveille.
à toi de voir comment l'implémenter si ça t'intérresse.

[cried-nutty-won]

install et uninstall fonctionnent parfaitement maintenant.
skill is now properly integrated in openfox