Reranking & retrieval

Retrieval in CiteNexus is a fixed, auditable pipeline: several retrievers each produce a ranked list, the lists are merged with Reciprocal Rank Fusion, and the fused head is optionally reranked by a cross-encoder you inject. Fusion lives in the core, so no plugin can bypass it — every candidate that reaches the grounding gate went through the same deterministic path.

The pipeline

1. Retrieve. Each enabled retriever runs against the query and returns a ranked candidate list.
2. Fuse. All lists are combined with RRF (k = 60): a candidate at zero-based rank contributes 1 / (k + rank + 1), merged by Evidence-Unit id.
3. Rerank. The fused head is reordered by the injected reranker against the original query (a no-op passthrough if you inject none).
4. Cut. The top top_k survive to grounding.

Retrievers and the signals that enable them

Which retrievers run is gated by the signals you declare on the client. Omit signals and all of them are built and queried.

Retriever	Enabled by signal	What it does
Vector (dense)	embedding (and an embedder is set)	nearest-neighbour over the vector store
Lexical (BM25)	text	BM25 / full-text search (Postgres tsvector or the in-core BM25)
Structure	structure	matches query terms to structure-node labels
Graph	graph / community	matches query terms to entity-node labels and returns that node’s Evidence Units (no edge walking — see graph)
Wiki	wiki	distilled-wiki navigation (slow path)

Python facade — Go and JavaScript have no equivalent

CiteNexus and the ingest / ask /evaluate / reconcile / delete verbs, plus the config layer they read, are the Python facade. The Go and JavaScript packages ship the deterministic core instead — the faithfulness gate, tokenizer, chunker, RRF and Result, at conformance parity — and enter through Ask / ask over an in-memory corpus (quickstart). The Python samples on this page have no port tab because there is nothing to put in it.

from citenexus import CiteNexus

# Lexical + vector only — no graph/wiki/structure built or queried.
rag = CiteNexus("./citenexus-data", embedder=..., generator=..., signals=["embedding", "text"])

Vector retrieval needs an embedder

The vector retriever only runs when the embedding signal is declared and an embedder is provided. With no embedder, the client is lexical-only.

Injecting a reranker

By default CiteNexus applies an identity passthrough (fusion order is kept). Inject OpenAICompatibleReranker to reorder the fused head with a cross-encoder. It POSTs {model, query, documents} to {base_url}/rerank and reads the Cohere/Jina-shape results[] (relevance_score + index).

from citenexus import CiteNexus
from citenexus.retrieve import OpenAICompatibleReranker

reranker = OpenAICompatibleReranker(
    base_url="http://localhost:11434/v1",   # any endpoint exposing POST {base_url}/rerank
    model="bge-reranker-v2-m3",
)

rag = CiteNexus(
    "./citenexus-data",
    embedder=..., generator=...,
    reranker=reranker,                       # replaces the default identity passthrough
    top_k=5,
)

Controlling top_k

top_k is how many candidates survive to grounding. Set a default on the client, or override it per call:

rag = CiteNexus("./citenexus-data", embedder=..., generator=..., top_k=5)  # default

response = rag.ask("What notice does termination require?", k=8)  # override for this call
docs   = rag.retrieve("termination notice", k=20)               # retrieval only, no generation

retrieve() returns the ranked candidates without generating an answer — the engine under ask(), and the escape hatch for wiring your own small model.

The reranker seam and `retrieve()` are Python-only

RRF fusion itself exists in all three languages (rrf.Fuse in Go, rrfFuse in JavaScript, plus the core-backed rrf). The reranker seam and retrieve() do not: the Go port’s Providers struct carries no Reranker field at all (there is nothing in that port that would call one), and JavaScript ships no rerank symbol either. Everything on this page below “The pipeline” describes the Python facade.

RRF, directly — in all three ports

The fusion function is public and pure, if you fuse ranked lists yourself. It is one of the algorithms pinned byte-for-byte across the ports (conformance/cases/rrf.json), so the fused order is identical in each:

Python

from citenexus.retrieve import rrf_fuse

fused = rrf_fuse([list_a, list_b], k=60)   # lists of Candidate objects

Go

import "github.com/muthuishere/citenexus/golang/rrf"

fused := rrf.Fuse([][]string{listA, listB}, rrf.DefaultK)  // DefaultK == 60
// rrf.Fuse([][]string{{"a", "b"}, {"b", "c"}}, 60) → [b a c]

JavaScript

import { rrfFuse } from "@muthuishere/citenexus";

const fused = rrfFuse([listA, listB], 60);
// rrfFuse([["a", "b"], ["b", "c"]], 60) → ["b", "a", "c"]

Same ranking, two shapes

Python’s rrf_fuse takes and returns Candidate objects — it is the fusion step inside retrieve(), so each hit keeps its eu_id, source signal, document_id and text attached through the merge. The Go and JavaScript Fuse / rrfFuse take and return Evidence-Unit id strings: they are the pure ranking primitive, and you rejoin the ids to your own rows. The scoring and the tie-break are the same in both shapes — 1 / (k + rank + 1) summed across lists, descending score, ascending eu-id on a tie.

Go also ships a core-backed core.Fuse (build tag citenexus_ffi) that shares one Rust implementation across the SDKs; the pure rrf.Fuse above is retained for the plain go get path and is byte-identical to it.