Jev RAG

Jev RAG / Tutorial

Practical Jev RAG tutorial

How to use Jev
for RAG.

Use a fast local retriever to find a bounded candidate set, let Jev judge which passages support the question, then ask a separate answer model to write only from the retained evidence. The default path needs no embeddings and no vector database.

Run Jev RAG locallyInspect the 323-query benchmark

Direct answer

Where does Jev fit in a RAG pipeline?

Jev fits between retrieval and generation. SQLite FTS5/BM25 retrieves up to 30 candidate passages from local files. Jev receives the question and those candidates, returns calibrated evidence scores, and the application sorts them. MiniMax then streams a cited answer from up to ten retained passages.

The local index stays on your machine, but selected passage text is sent to the configured Jev provider and answer model. This is local-first, not fully offline.

0 · Try local retrieval without a key

Search public docs before connecting a model.

This Python 3.9+ demo uses only the repository's public docs/ folder and a separate SQLite database. It does not scan your personal Documents folder, require package installation, or make a model request. SQLite FTS5 must be available.

git clone https://github.com/aifabrice/jev-rag.git
cd jev-rag
python3 local_kb.py --documents ./docs --db .knowledge/quickstart.db index
python3 local_kb.py --documents ./docs --db .knowledge/quickstart.db search 'retrieval' --no-jev

Expect ranked passages, source paths, and retrieval timing. This is the BM25-only baseline, not Jev reranking or a generated answer. Keep both folder and database arguments on every command. Once this works, continue with provider setup for the full pipeline.

1 · Install and configure

Start with the smallest working path.

Clone the repository, create an isolated Python environment, install the package, and copy the example environment file. Keep .env out of version control.

git clone https://github.com/aifabrice/jev-rag.git
cd jev-rag
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
cp .env.example .env

Configure the provider credentials described in the README. The default answer path uses OpenRouter; Jev can run through the configured TypeSafe or OpenRouter route.

2 · Index local files

BM25 needs searchable passages, not embeddings.

Point the CLI at a document folder. Markdown, text, HTML, JSON, CSV, YAML, DOCX, and PDF files are supported. The index is a local SQLite database.

jev-rag \
  --documents /absolute/path/to/documents \
  --db .knowledge/documents.db \
  index --rebuild

Short files can stay whole. Large files should normally use the default heading-aware passage splitting so retrieval, reranking, and citations operate on focused evidence. Use --chunking none only when whole-file records match your corpus and evaluation.

3 · Retrieve, rerank, answer

Run BM25 + Jev before adding more infrastructure.

jev-rag \
  --documents /absolute/path/to/documents \
  --db .knowledge/documents.db \
  serve

Open http://127.0.0.1:8765. The default mode runs local BM25 retrieval, batches up to ten candidates per Jev request, keeps the evidence order in application code, and streams the final cited answer.

You can also compare the stages from the CLI:

# Local lexical baseline; no Jev request
jev-rag --documents /absolute/path/to/documents --db .knowledge/documents.db search 'your question' --no-jev

# Default BM25 candidate retrieval followed by Jev
jev-rag --documents /absolute/path/to/documents --db .knowledge/documents.db search 'your question'

# Machine-readable evidence and timing
jev-rag --documents /absolute/path/to/documents --db .knowledge/documents.db search 'your question' --json

4 · Know what Jev can and cannot fix

Reranking improves order, not missing recall.

Use BM25 + Jev when

Your documents contain exact product names, identifiers, technical terms, or overlapping query language. It is fast, inspectable, and avoids an embedding index.

Add agentic lexical search when

The query needs several alternate lexical searches but you still do not want a document embedding index. The planner proposes searches; code executes and fuses them locally.

Add hybrid retrieval when

Synonyms and paraphrases cause BM25 to miss the right evidence. Embedding candidates widen recall before the same Jev reranking stage.

Measured result

Jev improved the BM25 shortlist; wider recall improved it further.

PipelinenDCG@10What changed
BM25 top 300.305654Local lexical baseline
BM25 top 30 + Jev0.353235Same candidates, Jev reranking
Agentic lexical + Jev0.430969Wider lexical recall, then Jev
Hybrid top 50 + Jev0.444327Lexical + semantic recall, then Jev

These are project-run results on the complete BEIR NFCorpus test split: 3,633 documents and 323 queries. They are not an official MTEB submission. Reproduce the commands and test your own corpus before choosing a pipeline.

Evaluation checklist

Measure the whole retrieval path.

  1. Check whether the answer-bearing passage appears in the BM25 candidate set.
  2. Compare its rank before and after Jev.
  3. Track first-token latency, total answer time, provider calls, and cost.
  4. Inspect whether every answer claim points to a retained source passage.
  5. Keep failed queries; they tell you whether to improve chunking, retrieval recall, reranking policy, or generation.
Run Jev RAG locallyCompare all pipelines

Continue with evidence

Choose the next Jev RAG reference.

Use the benchmark explorer to compare retrieval paths, the use-case guide to choose a corpus shape, or the FAQ to verify privacy and vector-database boundaries before you connect a provider.

Explore the BM25 + Jev benchmark → · Review local knowledge-search use cases → · Read the evidence-backed FAQ →