# agentic-rag-jdemo-3-reranker

**Repository Path**: createmaker/agentic-rag-jdemo-3-reranker

## Basic Information

- **Project Name**: agentic-rag-jdemo-3-reranker
- **Description**: agentic-rag-jdemo-3-reranker
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-03
- **Last Updated**: 2026-05-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# agentic-rag-jdemo-3-reranker

Demo 3 (Java) — **Cross-encoder reranker** on top of Demo 2's hybrid retriever. Mirror of the Python sibling.

## Why a reranker?

Demo 2 ends with `HybridRetriever` (BM25 + dense + RRF). Good for **recall**, but its top-1 ordering can still be off — bi-encoders embed query and doc independently and miss query-doc interaction signals. A cross-encoder takes (query, doc) **jointly** through the transformer and re-scores; ~10-50× more accurate at ranking, ~100-1000× slower per pair.

Two-stage retrieval gets the best of both:

```
                ┌──────── stage 1: recall ───────┐  ┌── stage 2: precision ──┐
question ──►   hybrid (BM25+dense+RRF, top-30)  ──►   cross-encoder rerank ──►  top-5
                └────────────────────────────────┘   └────────────────────────┘
```

## Java specifics

The Python sibling uses `sentence-transformers` in-process. In Java, running a torch cross-encoder requires DJL + ONNX runtime — heavy and platform-dependent. We mirror Demo 2's pattern instead:

- `HttpReranker` — calls an OpenAI-compatible `/rerank` endpoint (Cohere / Jina / TEI format)
- `OverlapReranker` — pure-Java token-Jaccard fallback (default, no server needed)

## What's new vs Demo 2 Java

- `Reranker.java` — interface + `OverlapReranker` (no-model) + `HttpReranker` (calls `/rerank` HTTP)
- `RerankRetriever.java` — wraps any base retriever, over-fetches and re-orders
- `Retrievers` exposes `.rerank()` (plus `.rerankerDescription()` for the banner)
- New tool **`search_rerank`** — promoted to default in the system prompt; `search_hybrid` demoted to "raw fusion" fallback
- `arag --compare` grows a 4th column (Rerank CE)

## Setup

```powershell
cd D:\javacode\agentic-rag-jdemo-3-reranker
mvn package
copy .env.example .env
```

## Run

```powershell
java -jar target\arag.jar --ping
java -jar target\arag.jar --list
java -jar target\arag.jar "How does the mobile app authenticate?"
java -jar target\arag.jar --compare "issue tracker workflow"
```

REPL banner shows the live reranker:

```
agentic-rag-jdemo-3-reranker  llm=http://localhost:8642/v1 (hermes-agent),
embed=http http://localhost:8642/v1 (bge-small-zh),
rerank=overlap (no model — Jaccard heuristic),
chunks=33
```

Set `RERANKER_BACKEND=http` (and `RERANKER_BASE_URL` / `RERANKER_MODEL`) to use a real cross-encoder server.

## Files

```
src/main/java/com/agentic/rag/
├── Reranker.java          # NEW — interface + OverlapReranker + HttpReranker
├── RerankRetriever.java   # NEW — over-fetch + rerank wrapper
├── Retrievers.java        # builds .rerank() too; exposes rerankerDescription()
├── Tools.java             # adds search_rerank as default
├── Agent.java             # system prompt promotes search_rerank
├── App.java               # --compare grows a 4th column; banner shows reranker
src/test/java/com/agentic/rag/
├── HashEmbedderTest.java / RrfTest.java / SafeEvalTest.java   # unchanged
└── RerankerTest.java      # NEW — 8 tests (Overlap + Wrapper, no server needed)
```

## Knobs

| env | default | what |
|---|---|---|
| `RERANKER_BACKEND` | `overlap` | `http` or `overlap` |
| `RERANKER_BASE_URL` | `LLM_BASE_URL` | `/rerank` endpoint base |
| `RERANKER_MODEL` | `bge-reranker-base` | model id sent to server |
| `RERANKER_API_KEY` | `LLM_API_KEY` | bearer token |
| `RERANKER_TIMEOUT_SEC` | `30` | per-request timeout |
| `RERANKER_OVER_FETCH` | `30` | candidates pulled from hybrid before rerank |

## Tests

```powershell
mvn test    # 5 HashEmbedder + 5 RRF + 10 SafeEval + 8 Reranker = 28 tests
```

## Cross-language sibling

Mirror at `D:\PythonProjects\agentic-rag-demo-3-reranker` (uses `sentence-transformers` CrossEncoder in-process; here it's HTTP — same conceptual two-stage pipeline).